Start with the smallest check
aidc version checks the command itself without loading your settings. aidc list TOOL shows installed releases, aidc current TOOL shows the selection, and the tool's own version command shows what the shell runs. Do not delete a working installation to repair a configuration or sign-in problem.
aidc: command not found
The shell cannot find the executable. Check where it was placed and whether that directory is on PATH. A command installed on your computer is not automatically present inside a container. The getting-started steps set up a user-owned installation and the shell.
A command fails before doing its work
Malformed YAML or a value of the wrong type stops startup, and the error can name an application setting rather than a tool. aidc help, aidc version and aidc completion still work. Correct the named setting, quote tool versions in .aidc.yaml, and keep a copy of a damaged file while you repair it. An unreadable settings file can be treated as absent, so defaults apply: check its permissions for the user that runs AIDC.
Setup finds nothing to install, or reports failures and exits 0
Setup reads only the current or named directory, and a missing .aidc.yaml looks like success. Name the project directory:
Setup also reports per-tool failures without failing the whole run. Read each result, run each required tool's version command, and retry failed tools from the project root.
The shell runs another version
Installation and shell activation are separate, and a profile change does not reach a shell that is already open. Open a new shell, then compare:
An alias, a shell function or a temporary aidc use choice can take precedence. For a non-interactive job, load the environment with eval "$(aidc env export bash)" first.
A tool or plugin is not found
use and set work only with installed versions, so install first, then select:
For a plugin name, check aidc plugin list: the name you install can differ from the executable it provides. A tool the plugin list does not know needs a newer AIDC release.
No matching release, or the package service is unreachable
Compare the packaged source with the vendor:
A release can exist upstream before a prepared package does. aidc doctor reports connectivity and sign-in state. When vendor installation is acceptable, set AIDC_HUB_ENABLED=false for the current environment and retry the explicit request, then restore the setting.
Checksum or signature verification failed
A rejected package is not extracted. Retry the same exact release once. A repeated mismatch needs investigation of the download, a proxy or the selected source. Keep the messages, so a later fallback success is not mistaken for acceptance of the rejected package. Do not treat a locally cached copy as a verified replacement.
A coding agent CLI looks logged out or rejects its runtime
AIDC keeps each agent's normal configuration home, so check that the container exposes it and that the runtime user can read it. Installing a new version does not copy accounts. Agents that run on a private runtime take it as the third install argument, for example aidc install aider latest python@3.12 or aidc install cline latest nodejs@22.
Upgrade, prune or a maintenance command does not do what you expect
Upgrade and prune need their own feature access, even for a dry run: run aidc login --check after access changes. upgrade --all can exit 0 with a failed tool, so compare aidc current afterwards and retry only that tool. Use --keep until the new release passes your project check. Prune sees only the current context, so review aidc prune TOOL --dry-run before removing anything another project still needs.
What you getThe tool you need installed, selected and confirmed by its own version command.