AIDC problems and fixes

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.

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.

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 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.

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.

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.

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.

Check the prepared releases for your platform with aidc list php --available. A vendor release can precede exact source-build support. PHP 8.5.11, 8.4.26, 8.3.35 and 8.2.34 have prepared Linux x86_64 and arm64 packages. Use the confirmed package from the project root, for example aidc install php@8.5.11 --hub, after preserving the project's .aidc.yaml: installation changes its selection by default. An older AIDC needs exact source support; a compatible newer installer can extend a stable patch within an already supported minor line. Keep the previous patch until PHP and project checks pass.

Check the first failing command and the compiler, development libraries, HTTPS access, free disk space and writable data and temporary directories. Source builds need these resources and may need permission to install system packages. Correct the named prerequisite or use a prepared package for the intended platform. A successful source download does not prove a successful interpreter.

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.

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 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.

Muse versions carry a build suffix such as 1.3.0-R3057.1, and the vendor serves only latest, a full build or the shortened form of its current release. Compare your request with the full build recorded for your project, then request that full build or latest.

Kiro is supplied directly by its vendor, so the package service has no Kiro package. Check that the environment can reach the vendor download, then run aidc install kiro.

aidc update stores the new release beside the installed aidc, and in the MAIT image that folder belongs to the system. Check where aidc is installed with command -v aidc. Move to a newer MAIT image, or keep a self-installed aidc in a folder you own.

aidc update downloads and verifies the newer release. The next aidc command you run, including aidc version, switches to it first, so aidc version then reports the newer release. If aidc cannot switch, it prints a warning that the downloaded update could not be applied and runs your command on the version you had. Read the reason in the warning: a permission problem means aidc sits in a folder your account cannot write to, so move to a newer MAIT image or keep aidc in a folder you own. For any other repeated reason, replace the executable with the newer one, confirm with aidc version, then delete the hidden .aidc.update. files beside it.

aidc update asks before installing, and a script or remote command cannot answer. Check whether the command ran without a terminal. Run it in a terminal, or add --force once the update is approved; force does not skip verification.

aidc legal lists only the components built into the aidc executable. Check that the missing item is a tool AIDC installed, such as Node.js. Read that tool's own documentation or licence files under the folder shown by aidc where TOOL.