Refined error message or code when core install fails due to an issue in 3rd-party platform's archive structure

[dankeboy36]

Describe the request

When installing a 3rd-party core fails due to an error in the platform's archive structure, the CLI returns a technically correct error message. However, the error message could be challenging to understand for the end user. This can happen when tools decide to show the verbatim error message received from the CLI in a UI as is. For example,

searching package root dir: no unique root dir in archive, found '/path/to/directories.data/tmp/package-4129751842/cores' and '/path/to/directories.data/tmp/package-4129751842/firmwares'

Clients of the CLI could try to translate this error message, but it is a generic internal error.

---

CLI can provide a less technical error message, helping the user resolve the issue

OR

CLI can provide a finer-grained error code so tools can handle this specific error

Describe the current behavior

Terminal 1:

cat my-arduino-cli.yaml

board_manager:
    additional_urls:
        - https://udooboard.github.io/arduino-board-package/package_udoo_index.json
directories:
    builtin:
        libraries: /Users/akoskitta/Library/Arduino15/libraries
    data: /Users/akoskitta/dev/git/arduino-cli/tmp_data
    user: /Users/akoskitta/dev/git/arduino-cli/tmp_user

./arduino-cli version
arduino-cli  Version: git-snapshot Commit: 77b3e150 Date: 2026-03-17T09:28:14Z

./arduino-cli daemon --config-file my-arduino-cli.yaml
Daemon is now listening on 127.0.0.1:50051
{"IP":"127.0.0.1","Port":"50051"}

Terminal 2:

buf export . -o ./tmp/out

grpcurl \
  -plaintext \
  -import-path ./tmp/out \
  -proto cc/arduino/cli/commands/v1/commands.proto \
  127.0.0.1:50051 \
  cc.arduino.cli.commands.v1.ArduinoCoreService.Create

{
  "instance": {
    "id": 1
  }
}

grpcurl \
  -plaintext \
  -import-path ./tmp/out \
  -proto cc/arduino/cli/commands/v1/commands.proto \
  -d '{"instance": {"id": 1}}' \
  127.0.0.1:50051 \
  cc.arduino.cli.commands.v1.ArduinoCoreService.Init

empty stdout

grpcurl \
  -plaintext \
  -import-path ./tmp/out \
  -proto cc/arduino/cli/commands/v1/commands.proto \
  -d '{"instance": {"id": 1}, "platform_package": "UDOO", "architecture": "sam"}' \
  127.0.0.1:50051 \
  cc.arduino.cli.commands.v1.ArduinoCoreService.PlatformInstall

{
  "taskProgress": {
    "name": "Tool UDOO:bossac-udoo@1.3a-1.0 already installed",
    "completed": true
  }
}
{
  "taskProgress": {
    "name": "Tool arduino:arm-none-eabi-gcc@4.8.3-2014q1 already installed",
    "completed": true
  }
}
{
  "taskProgress": {
    "name": "Downloading packages"
  }
}
{
  "progress": {
    "start": {
      "url": "https://udooboard.github.io/arduino-board-package/udooqdl-arduino-sam-1.6.7.tar.bz2",
      "label": "UDOO:sam@1.6.7"
    }
  }
}
{
  "progress": {
    "end": {
      "success": true,
      "message": "UDOO:sam@1.6.7 already downloaded"
    }
  }
}
{
  "taskProgress": {
    "completed": true
  }
}
{
  "taskProgress": {
    "name": "Installing platform UDOO:sam@1.6.7"
  }
}
ERROR:
  Code: Internal
  Message: Cannot install platform: installing platform UDOO:sam@1.6.7: searching package root dir: no unique root dir in archive, found '/Users/akoskitta/dev/git/arduino-cli/tmp_data/tmp/package-318803292/cores' and '/Users/akoskitta/dev/git/arduino-cli/tmp_data/tmp/package-318803292/firmwares'

Arduino CLI version

77b3e15

Operating system

macOS

Operating system version

26.3.1

Additional context

#2131

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the nightly build
• My request contains all necessary details