Troubleshooting

Diagnostics and tips

By default, setup and doctor show progress on stderr. Other commands are silent. Explicit --verbose none silences progress and diagnostics. Non-interactive execution writes only its JSON result to stdout. Interactive commands also print prompts, and help/version output is plain text. Pass --verbose <level> to activate diagnostic output on stderr.

cube agentic-ai --verbose standard project-add <bundle> <project>   # step-by-step progress
cube agentic-ai --verbose debug   project-add <bundle> <project>   # full sub-step trace

Level

What appears on stderr

none

Nothing. Default for commands other than setup and doctor.

progress

Default for setup and doctor; also enables per-item progress for other commands.

standard

Progress plus INFO, ERROR, and CRITICAL messages

debug

All of the above plus resolved paths, per-file copy trace, raw values

--verbose is a root-level flag. Example:

# Diagnose a failing project-add
cube agentic-ai --verbose debug project-add cube-agentic-ai-programmer /my/project 2>debug.log

Both stdout and stderr can be captured independently:

cube agentic-ai --verbose standard project-add <bundle> <project> > result.json 2>progress.log

On failure, every command writes a JSON object with ok: false and a structured error block to stdout. The exit code is non-zero (see Commands → Output envelope).

Other useful practices:

  • Use --dry-run with machine-bootstrap, project-deploy, project-deploy-installed, or project-remove to preview changes. machine-install and project-add do not have this option.

  • If a command hangs, cube may be waiting on a network operation — check connectivity and retry.

  • After a partial project-remove failure, or when lock-source drift is detected, services-lock.json may be marked tainted (integrity.state = UNRELIABLE): inspect the actual project state. See Lock files for details.

  • If command output includes warning code CONNECTOR_VERSION_MISMATCH, run cube agentic-ai project-lock-show <project> and inspect lock state before the next mutating operation.

Error codes

Codes specific to one command are noted in the Meaning line.

ADVISORY_ONLY

Meaning: --autodetect-targets advisory found missing target dimensions, reported the detected candidates, and intentionally stopped before installation or deployment. This is expected behavior, not an error.

Action: Review the detected ide and agentic-system candidates in the JSON output, then rerun with explicit --ide and --agentic-system values, or switch to --autodetect-targets enforce if you want the installer to apply detected values automatically.

ALL_BUNDLES_FAILED

Meaning: (setup, machine-bootstrap, project-deploy, project-deploy-installed) All accepted or processed bundles were attempted and every one failed. No contexts were deployed. Setup stops before its project-folder creation step. Per-bundle causes are in error.details.results for machine bootstrap/setup or error.details.failedBundles for deploy commands.

Action:

  1. Run with --verbose debug to see the per-bundle error details.

  2. For project deploy commands, inspect data.bundles[].error.code when the command returns a partial success, or error.details.failedBundles when all bundles failed.

  3. For machine-bootstrap or setup, inspect data.results[] on partial success, or error.details.results when all bundles failed.

  4. Fix the root cause for each bundle and retry the same command. After setup returns PARTIAL, use the project-scoped project-add and doctor --fix commands in its data.nextSteps. Setup cannot be rerun once it has deployed contexts.

ARTIFACT_DUPLICATE_DESTINATION

Meaning: Two incoming artifacts resolve to the same target path or skill directory.

Action: Review the reported owners and destination, then rename or move the user-owned file, change the selected deployment, or skip one of the conflicting artifacts before retrying.

ARTIFACT_USER_OWNED_CONFLICT

Meaning: An existing destination is not recorded as installer-managed and is treated as user-owned or unknown.

Action: Rename or move the file, or change the selected deployment before retrying. The installer does not silently overwrite user files.

ARTIFACT_CONNECTOR_SERVICE_CONFLICT

Meaning: The destination is already managed by another service or artifact from the same context.

Action: Fix the context artifact mapping or change the selected deployment. The installer does not allow one service or artifact to replace another within the same context.

ARTIFACT_CROSS_CONNECTOR_CONFLICT

Meaning: The destination is recorded as managed by a different context.

Action: Keep the existing context, remove it before deploying the new context, or change the incoming artifact destination. The installer does not allow one context to replace another context’s managed artifact. Report this conflict to the bundle owner if it is unexpected.

ARTIFACT_CONTENT_HASH_MISMATCH

Meaning: The destination belongs to the incoming logical artifact, the incoming service version is the same as the recorded version, but its current contents no longer match the hash recorded when the installer last deployed it.

Action: Review the file for intentional user changes. Preserve or move those changes, then retry deployment. A different version of the same logical service is an intentional upgrade and is not reported with this error.

SERVICES_LOCK_SCHEMA_UNSUPPORTED

Meaning: The project services lock does not use the hash-backed schema required for ownership-aware replay.

Action: Perform a clean deployment that creates the current services-lock schema, then retry the replay. The installer does not infer ownership from legacy path-only records.

PROJECT_REMOVE_REQUIRED_SERVICE_CONFIRMATION_REQUIRED

Meaning: A partial project-remove request includes a service recorded as required, while another service from the same context will remain deployed. Removing it may impede the remaining services.

Action: Confirm the interactive prompt, or rerun the command with --confirm-always. Removing the whole context, or removing all deployed services, does not require confirmation. Legacy lock entries without a required/optional tag are treated as optional.

ARTIFACT_ENTRYPOINT_MISSING

Meaning: A selected skill, agent, instruction, or prompt source/entrypoint is missing.

Action: Check the bundle source path and selected fileFamilies entry.

ARTIFACT_METADATA_INVALID

Meaning: Required kind-specific metadata cannot be validated or normalized.

Action: Inspect the artifact frontmatter and target profile requirements.

ARTIFACT_KIND_UNDEFINED

Meaning: The context bundle contains inconsistent artifact metadata. The installer cannot determine a valid semantic kind for one of the declared artifacts.

Action: Reinstall or update the context bundle. If the problem persists, report the bundle name, version, and error details to the bundle owner. Bundle metadata must use supported kinds (skill, agent, instruction, prompt, or resource) consistently.

ARTIFACT_NAME_INVALID

Meaning: An artifact identity does not satisfy the registered or host naming rules.

Action: Check artifacts.name and the selected target profile.

ARTIFACT_REFERENCE_KIND_MISMATCH

Meaning: A skill://, agent://, instruction://, or prompt:// reference does not match the declared artifact kind.

Action: This indicates inconsistent bundle metadata or capabilities.md content. Reinstall or update the context bundle and report the bundle name, version, reference, and error details to the bundle owner.

ARTIFACT_REFERENCE_MISSING

Meaning: A selected artifact is not referenced in the filtered capabilities.md content for the deployed service set.

Action: Check that the selected service’s capabilities.md section references its declared artifact with the matching skill://, agent://, instruction://, or prompt:// scheme. Report the bundle name, service, and artifact identity to the bundle owner if the reference is missing from the context content.

ARTIFACT_REFERENCE_UNKNOWN

Meaning: A semantic artifact reference has no corresponding entry in the installer-provided replacement map.

Action: This indicates an incomplete or inconsistent context bundle. Reinstall or update the bundle and report the bundle name, version, reference, and error details to the bundle owner. It is not a user-file naming issue.

ARTIFACT_RESOURCE_OWNS_RESOURCE

Meaning: A context bundle declares a kind: "resource" artifact with its own non-empty resources list. Resource artifacts are supporting files and cannot own other resources.

Action: Reinstall or update the context bundle. If the problem persists, report the bundle name, version, artifact identity, source path, and nested resource list to the bundle owner. The bundle owner must move those nested resources to the owning skill, agent, instruction, or prompt artifact’s resources list.

BUNDLE_INSTALL_FAILED

Meaning: cube could not install one or more bundles (network error, registry unavailable, or version not found).

Action:

  1. Check network connectivity.

  2. Verify the bundle name and version: cube agentic-ai machine-discovery lists what is available locally. The command cube bundle list-online lists the registry.

  3. Retry. If the error persists, check the Cube registry status.

BUNDLE_LOCKED_VERSION_NOT_INSTALLED

Meaning: (project-add, project-deploy) With --bundle-version-policy lock-driven, the command requires the version already locked for the bundle, but that exact version is not installed on the machine.

Note

project-deploy-installed does not accept --bundle-version-policy. Its candidates are already pinned (name@version from installed inventory).

Action:

  1. Inspect project lock state with cube agentic-ai project-lock-show <project> and identify the required bundle version.

  2. Install the missing version (cube bundle install <bundle>@<version>), then rerun the command.

  3. If you intentionally want to proceed without the locked version, rerun with --bundle-version-policy flexible.

BUNDLE_NOT_DEPLOYED

Meaning: (project-remove) The bundle is not deployed in the project.

Action: Run cube agentic-ai project-lock-show <project> to see what is currently deployed, then retry with a valid bundle name.

BUNDLE_NOT_FOUND

Meaning: A requested bundle is not installed on the machine and could not be located.

Action: Verify the bundle name with cube agentic-ai show-catalog, then run cube agentic-ai machine-install <bundle_name>, or use cube agentic-ai project-deploy with --auto-install-missing (default true).

BUNDLE_NOT_IN_AI_CATALOG

Meaning: (machine-install, setup --contexts, doctor --bundles) The bundle name is not a supported STM32Cube Agentic Context bundle.

Action: Run cube agentic-ai show-catalog to see supported contexts. Use cube agentic-ai machine-discovery to see what is already installed. To install another kind of bundle, use cube bundle install <bundle_name> directly.

CATALOG_INVALID

Meaning: (show-catalog, machine-bootstrap, machine-install, machine-discovery, project-add, project-deploy) Context catalog data is invalid.

Action: Reinstall the installer bundle or restore a valid catalog version.

CATALOG_NOT_FOUND

Meaning: (show-catalog, machine-bootstrap, machine-install, machine-discovery, project-add, project-deploy) The context catalog is unavailable.

Action: Reinstall the installer bundle and retry.

CATALOG_PARSE_ERROR

Meaning: (show-catalog, machine-bootstrap, machine-install, machine-discovery, project-add, project-deploy) The context catalog could not be read.

Action: Reinstall the installer bundle, or fix the malformed catalog file if working in a development checkout.

CATALOG_VALIDATION_FAILED

Meaning: A catalog file under data/ failed schema validation (missing field, wrong type, or unknown version). Indicates a corrupted or incompatible installer bundle.

Action: Re-install the installer bundle:

cube bundle install cube-agentic-ai-installer --yes

CUBE_BUNDLE_INFO_ERROR

Meaning: (machine-discovery) The installer could not inspect an installed context’s Cube tool dependencies.

Action: Reinstall the affected context bundle and retry. If the issue persists, run with --verbose debug and report the bundle name and error details to support.

CUBE_LIST_ERROR

Meaning: (machine-discovery) cube bundle list failed while reading installed machine inventory.

Action: Verify cube is installed and functional, then retry. Use cube agentic-ai --verbose debug machine-discovery for details.

CUBE_NOT_FOUND

Meaning: The cube binary is not on PATH.

Action: Complete the bootstrap first: https://dev.st.com/stm32cube-agentic-ai/stm32cube-agentic-ai-start/index.html On Windows, open a new terminal after installation so the updated PATH takes effect.

INVALID_OPTION_COMBINATION

Meaning: (machine-discovery) --json-file was passed while --no-json disabled machine catalog file generation.

Action: Remove --json-file, or re-enable file generation by omitting --no-json.

INVALID_USAGE

Meaning: The CLI arguments or options are invalid, for example an unknown command, an invalid option value, a missing required argument, or an empty machine-discovery --json-file value.

Action: Read error.message and run cube agentic-ai <command> --help to check the syntax. For machine-discovery --json-file, provide a non-empty path value.

JSON_FILE_WRITE_FAILED

Meaning: (machine-discovery) Machine catalog file output could not be written.

Action: Verify target folder write permissions, ensure parent directories can be created, or choose another --json-file path.

LEGACY_CUBE_PROJECT_LOCK_UNSUPPORTED

Meaning: (project-add, project-remove, project-lock-show) The project still has a Cube bundle lock created by an older installer version under <canonicalRoot>/.settings/bundles.store.json (e.g. .cube-ai/.settings/), instead of the project’s shared .settings/ folder. This legacy layout is no longer supported and the command is rejected without modifying any lock file.

Action:

  1. Inspect the legacy lock at the path given in error.cause/error.details.legacyLockPath and the project’s shared .settings/bundles.store.json (if any).

  2. Reconcile the bundle references into the shared .settings/bundles.store.json (or remove the legacy folder if its references are already reflected there).

  3. Rerun the command.

LIST_SUPPORTED_TARGETS_FAILED

Meaning: (list-supported-targets) Unclassified failure while reading the supported deployment targets.

Action: Rerun with --verbose debug, capture stdout/stderr, and report the failure with the emitted error.cause.

LOCK_READ_ERROR

Meaning: The project services lock file (.cube-ai/services-lock.json) is present but cannot be read or parsed.

Action: Back up and inspect the file, then restore a valid copy from source control when available. Do not delete it blindly: it records managed-file ownership required for safe replay and removal.

MACHINE_DISCOVERY_FAILED

Meaning: (machine-discovery) Unclassified failure.

Action: Rerun with --verbose debug, capture stdout/stderr, and report the failure with the emitted error.cause and error.details.

MANUAL_NOT_FOUND

Meaning: (get-user-manual) Documentation files could not be located in the installed bundle.

Action: Reinstall the installer bundle to restore its embedded manual. When working from a source checkout, regenerate the HTML and bundled Markdown through the supported synchronization script:

# from the installer source
bash update-user-manual.sh

MCP_CONFIG_PARSE_FAILED

Meaning: A bundle’s MCP configuration file or project’s MCP manifest could not be parsed as JSON/JSONC.

Action:

  1. The file may have syntax errors (missing commas, unescaped quotes, invalid comments).

  2. Check the file path in the error details for the exact location.

  3. For VS Code workspace manifests (.vscode/mcp.json), ensure the server map is valid JSON under top-level servers.

  4. If you copied a settings.json-style wrapper ({"mcp":{"servers":...}}) into .vscode/mcp.json, rewrite it as top-level servers.

  5. Fix the JSON syntax and retry, or delete the file to reset it.

  6. If the error is in a bundle-provided file, the bundle installation may be corrupted — re-install it.

MCP_FORMAT_INCOMPATIBLE

Meaning: MCP configuration files use incompatible formats or structure (e.g., source is .json but target is .yaml, or the servers key is not found).

Action:

  1. Ensure both the bundle MCP file and project MCP manifest use the same file format.

  2. Ensure the MCP payload contains a recognized server map: servers, mcpServers, or mcp.servers.

  3. When the project MCP manifest already exists, the installer preserves that existing key path and merges bundle servers into it.

  4. When the project MCP manifest is created, the installer uses the selected target’s required key path (for example servers for VS Code or mcpServers for Claude Code).

  5. A sidecar file (mcp-st<ext>) may have been created next to the target for manual inspection.

MCP_MERGE_CONFLICT

Meaning: The bundle tries to define a server with the same name as an existing server in the project, but the configurations differ.

Action:

  1. This protects your project from losing custom server configurations.

  2. A sidecar file (mcp-st<ext>) has been created next to your project’s MCP manifest.

  3. Manually merge the two files, keeping the configuration that is correct for your project.

  4. Delete the sidecar file after merging.

  5. Retry the deploy command.

Note

The installer normalizes MCP shape only when it creates a missing target manifest. Existing project manifests keep their detected key path so user-managed MCP files are not migrated during a merge.

MCP_SERIALIZATION_FAILED

Meaning: The merged MCP configuration could not be serialized back to JSON. This is an internal error and should not occur in normal operation.

Action: Check the error details and report it as a bug.

NO_SUPPORTED_TARGET

Meaning: (list-supported-targets) The target matrix catalog flags no supported IDE or agentic-system target.

Action: Re-install the installer bundle to restore a valid data/deployment-targets.json.

PATH_TRAVERSAL_DETECTED

Meaning: A source or destination path escapes its permitted bundle or project root.

Action: Remove path traversal segments and retry.

PRESET_INVALID

Meaning: (project-deploy) The preset file is not valid JSON, does not satisfy the expected schema, or contains a service provenance entry that cannot be replayed. A valid tagged entry uses <serviceId>@<bundleVersion>|required or <serviceId>@<bundleVersion>|optional. A legacy entry without the tag remains valid and is treated as optional.

Action: Inspect the file for JSON syntax errors and malformed service provenance. If the preset was generated by project-lock-show, re-export it because it may have been manually edited. Each context entry must have name, version, and serviceProvenance. Each provenance entry must contain a usable service ID and bundle version. Tool-dependency entries must not include serviceProvenance.

PRESET_NOT_FOUND

Meaning: (project-deploy) The path passed to --preset does not exist or is not a file.

Action: Verify the path. To generate a valid preset from an existing project, use cube agentic-ai project-lock-show <project> > preset.json.

PROJECT_DEPLOY_INVALID_OPTIONS

Meaning: (project-deploy) An invalid option combination was provided. This currently applies when --preset-no-reconcile is used without --preset.

Action:

  1. Provide a preset file with --preset <config_file> when using --preset-no-reconcile.

  2. Or remove --preset-no-reconcile and run standard deploy mode.

PROJECT_NOT_FOUND

Meaning: The provided project_top_folder does not exist or is not a directory.

Action: Verify the path or create the directory first. Generated firmware and Cube project metadata are not required before deploying agentic contexts.

PROJECT_REMOVE_FAILED

Meaning: (project-remove) Removal could not be completed due to a generic internal failure.

Action: Re-run with --verbose debug, then follow the more specific error code if one is provided.

PROJECT_REMOVE_IO_FAILED

Meaning: (project-remove) A filesystem I/O failure occurred during deletion of managed paths (for example lock, permission change, or other runtime FS error).

Partial deletion may already have occurred before the failure.

Action:

  1. Re-run with --verbose debug and inspect failedPath, deletedPaths, and pendingPaths in error details.

  2. Resolve the failing path condition (permissions, file lock, path state).

  3. Re-run project-remove.

  4. If needed, manually reconcile partially removed files using the reported path lists.

PROJECT_REMOVE_MANAGED_PATHS_MISSING

Meaning: (project-remove) One or more managed files expected by the computed removal plan are not present at their managed paths.

This can happen after canonical deployment when files were manually reshuffled from .cube-ai/ to non-canonical locations.

Action:

  1. Re-run with --verbose debug to inspect the computed removal paths.

  2. Check whether files were moved after deployment (especially after --canonical runs).

  3. Move files back to the expected managed paths.

  4. Re-run project-remove.

PROJECT_REMOVE_PERMISSION_PRECHECK_FAILED

Meaning: (project-remove) Preflight detected insufficient permissions for one or more managed removal targets.

Action:

  1. Re-run with --verbose debug and inspect the failing path details.

  2. Check file and directory permissions/ACLs for the managed targets.

  3. Close processes that may lock files.

  4. Fix permissions and re-run project-remove.

ROUTING_SECOND_CHOICE_POLICY_INVALID

Meaning: The orchestrator’s bundled second-choice routing policy does not match its schema or contains duplicate tier or service IDs. This is an internal policy-data error.

Action: Update or reinstall the installer bundle so its orchestrator policy and validator are from the same release. If the error persists, report the error code, installer version, and diagnostic details to support.

ROUTING_SECOND_CHOICE_SCHEMA_UNSUPPORTED

Meaning: The orchestrator cannot load the schema version declared by its bundled second-choice routing policy.

Action: Update or reinstall the installer bundle so its orchestrator policy and validator are from the same release. If the error persists, report the error code, installer version, and diagnostic details to support.

SERVICES_LOCK_UNRELIABLE_WRITE_FAILED

Meaning: During project-remove, at least one managed file was already deleted, then another deletion failed. When the installer tried to mark services-lock.json as integrity.state = UNRELIABLE, writing that marker also failed.

Action:

  1. Treat the lock state as potentially stale.

  2. Inspect current project files and compare with lock content.

  3. Repair or regenerate lock state before further mutating operations.

SERVICES_SCHEMA_UNSUPPORTED

Meaning: (project-add, project-deploy) The selected context bundle uses a deployment format that this installer release does not support. With --canonical, supported contexts can still deploy to the portable .cube-ai/ layout.

Action: Update the installer and context bundle, then retry. If the error persists, report the context bundle name, version, and error details to support.

SERVICES_VALIDATION_FAILED

Meaning: A service selection passed via --services is invalid (unknown service ID or explicit empty value).

Action: For project-add, inspect the context’s --list-ai-services output or its services.json. Omit --services for default and required services, or pass --services all to deploy every service. For project-remove, inspect project-lock-show and use IDs currently deployed in that project. Omit --services to remove the whole context.

SHOW_CATALOG_FAILED

Meaning: (show-catalog) The installer could not display the supported contexts.

Action:

  1. Re-run with --verbose debug and capture stdout/stderr.

  2. If the error is one of CATALOG_NOT_FOUND, CATALOG_PARSE_ERROR, or CATALOG_INVALID, follow the catalog-specific action above.

  3. If the command still returns SHOW_CATALOG_FAILED, report the failure with error.cause and error.details.

TARGET_AMBIGUOUS

Meaning: --autodetect-targets enforce was used but detection found multiple possible targets and could not resolve to one unambiguously.

Action: Provide explicit --ide and --agentic-system flags, or switch to --autodetect-targets advisory to see the suggestions without failing.

TARGET_CHANGED_IN_DEPLOYED_PROJECT

Meaning: The project already has deployed contexts, and the command asked for another --ide, --agentic-system or --canonical. A project has one target: deploying to another would leave the files and MCP servers of the first deployment behind, outside the lock. The command stops before writing any file.

Action: Read error.details.recordedTarget and use the same --ide and --agentic-system. To move the project to the requested target, run project-remove for each deployed context, then deploy again with the new target.

TARGET_COMBINATION_NOT_SUPPORTED

Meaning: The --ide value was not validated with the selected --agentic-system. The command stops before writing any file.

Action: Pick one of the IDEs listed in error.details.supportedIdes, for example --ide none for a CLI session. See Target selection for the accepted pairs.

TARGET_NOT_DETECTED

Meaning: --autodetect-targets enforce was used but no IDE or agentic-system marker was found in the project folder. The installer refuses to fall back silently to defaults.

Common situations:

  • The project folder is empty or freshly created (no .vscode/, .github/, .cursor/, etc.).

  • --ide or --agentic-system was omitted while targeting a tool whose folder markers do not exist yet.

Action:

  1. Check details.targetType in the error JSON (ide or agenticSystem) to know which dimension failed.

  2. Provide the failing dimension explicitly, or create the expected marker first (e.g. open the project in VS Code so .vscode/ is created). You can mix explicit and autodetected dimensions:

cube agentic-ai project-add <bundle> <project> --autodetect-targets enforce --agentic-system github-copilot
cube agentic-ai project-add <bundle> <project> --autodetect-targets enforce --ide vscode

  1. To inspect candidates without failing, use advisory mode first:

cube agentic-ai project-add <bundle> <project> --autodetect-targets advisory

TARGET_PROFILE_UNSUPPORTED

Meaning: The requested IDE/agentic-system tuple has no supported projection profile.

Action: Use a supported target or deploy with the canonical layout.

USER_JOURNEY_POLICY_INVALID

Meaning: The orchestrator’s bundled user-journey policy, which defines skills such as cube-agentic-ai-user-journey-mx2-cmake-build, does not match its schema or contains duplicate journey, skill, or step IDs. This is an internal policy-data error.

Action: Update or reinstall the installer bundle so its orchestrator policy and validator are from the same release. If the error persists, report the error code, installer version, and diagnostic details to support.

USER_JOURNEY_SCHEMA_UNSUPPORTED

Meaning: The orchestrator cannot load the schema version declared by its bundled user-journey policy.

Action: Update or reinstall the installer bundle so its orchestrator policy and validator are from the same release. If the error persists, report the error code, installer version, and diagnostic details to support.

Codes of setup and doctor

VS Code extension repair failures

With doctor --fix --vscode-profile "<name>", inspect data.vscodeInstall and data.fixes even when ok is true:

Result

Cause and action

PROFILE_UNAVAILABLE

The named profile could not be listed. Check its exact name in VS Code and the returned details. Create it manually if needed, then retry. No extension was installed there.

CODE_FAILED

code was absent, failed to start, or timed out. Fix PATH/launcher access or use that profile’s Extensions view. The extension state is unknown, not known missing.

Extension FAILED

The download/install command failed. Read its details for network, marketplace or permission errors, fix the cause and retry the same command. Already-installed extensions are not reinstalled or updated.

Without an explicit profile, --fix intentionally leaves extensions manual. Supply the exact profile name to authorize automatic repair. These results describe the named profile, not whether the active VS Code window has loaded the extension. Reload that window after installation.

CONTEXTS_EMPTY

Meaning: (setup, doctor) --contexts or --bundles was given without any bundle name.

Action: Name at least one catalog bundle, or omit the option. cube agentic-ai show-catalog lists the names.

CONTEXT_REQUIRES_VSCODE

Meaning: (setup) A context named with --contexts needs VS Code with STM32CubeIDE for Visual Studio Code, and the target is another IDE or the canonical layout. error.details.bundleNames lists them. Without --contexts, such contexts are skipped and listed in data.unavailableContexts instead of failing the run.

Action: Remove the context from --contexts, or use --ide vscode without --canonical.

BUNDLE_IDE_NOT_SUPPORTED

Meaning: (project-add) The bundle lists the IDEs it supports in its services.json, and the IDE of the request is not one of them, or --canonical was given. A bundle that lists no IDE supports every IDE. error.details has the bundle, its IDEs and the requested IDE.

Action: Use an --ide that the bundle lists, without --canonical, or leave the context out.

INVALID_PYTHON_CHOICE

Meaning: (setup) --python is not auto, venv, or the absolute path of an existing Python executable.

Action: Use --python auto, --python venv, or --python "<absolute path to python>".

INVALID_VSCODE_PROFILE_NAME

Meaning: (setup, doctor) A --vscode-profile name uses characters other than letters of any script (Chinese, Japanese and Korean included), digits, spaces, dots, underscores and hyphens, starts with something else than a letter or digit, or is longer than 64 characters.

Action: Use the exact name of the profile as VS Code shows it. Create the profile in VS Code first if it does not exist.

PROJECT_FOLDER_UNSAFE

Meaning: (setup) --project-folder is the home folder or a file system root.

Action: Choose a dedicated folder, for example <home>/my-agentic-ai-project (the default).

PROJECT_FOLDER_CREATE_FAILED

Meaning: (setup) The project folder cannot be created: its path exists and is not a folder, or the permissions do not allow it. error.cause has the path and the reason.

Action: Pick another path, or fix the permissions, then rerun setup.

SETUP_PROJECT_ALREADY_DEPLOYED

Meaning: (setup) The project folder already has a services lock: contexts were deployed there before. setup works only for a project folder that has never been deployed. error.cause has the path of the lock.

Action: Choose another project folder for a new deployment. To change this project’s contexts, use project-add or project-remove, then doctor <project_top_folder> --fix. If the desired context version is not installed yet, run machine-bootstrap --upgrade-installed-in-range true first.

SETUP_FAILED and DOCTOR_FAILED

Meaning: An unexpected error stopped setup or doctor before it could report.

Action: Rerun with --verbose debug and capture stdout and stderr. Report error.cause if it persists.

Warnings of setup and doctor

These codes appear in data.warnings[] and do not fail the command.

Code

Meaning

Action

REQUIREMENTS_DECLARATION_INVALID

The requirements of a bundle do not match the schema. They are ignored, and the bundle is checked without them.

Update the bundle. Report it to its owner if it is up to date.

IDES_DECLARATION_INVALID

The ides declaration of a bundle is not valid, or its services.json is older than 3.1.0. It is ignored.

Update the bundle.

IDE_DECLARATION_DIFFERS

The bundle lists IDEs that the installer catalog entry does not list, or lists none. The bundle’s own list decides which deployments are refused. The catalog only decides which contexts setup installs.

None for the user. Update the installer to get the matching catalog.

VSCODE_INSTALL_SKIPPED

(setup --install-vscode-extensions) The option did not apply: the target is not VS Code (another --ide, or --canonical), no installed context declares an extension, or code is not on the PATH. data.vscodeInstall.reason says which. Nothing was installed by the installer.

Use --ide vscode without --canonical, or run the commands of data.vscodeProfiles yourself.

VSCODE_INSTALL_INCOMPLETE

(setup --install-vscode-extensions) A profile could not be listed (usually a wrong name; the installer never creates a profile), code failed, or an extension did not install. data.vscodeInstall.profiles[] has the cause of each.

Fix the profile name, or install what is missing with the commands of data.vscodeProfiles or from the Extensions view.

VSCODE_CLI_NOT_FOUND

(setup) An installed context declares a VS Code extension and the code command is not in a PATH directory, so the extensions could not be checked or installed from the terminal. They are not necessarily missing.

Install them from the Extensions view of VS Code, or accept the proposal that VS Code makes when the folder opens. To get code: on macOS, run the Command Palette command “Shell Command: Install ‘code’ command in PATH” (named “Install ‘code’ and optionally ‘copilot’ commands in PATH” in recent versions); on Windows and Linux, reinstall VS Code or add its bin folder to the PATH. See the VS Code command line reference.

RECOMMENDATIONS_NOT_WRITTEN

Writing .vscode/extensions.json failed (permissions, locked file). A file with comments or an unexpected shape does not raise it: it is left unchanged and reported as NOT_UPDATED in data.recommendations.

Add the extensions of data.vscodeExtensions to its recommendations yourself.

LICENSES_UNKNOWN_BEFORE_INSTALL

(setup --dry-run) The licenses of bundles that are not installed yet cannot be read.

Run setup and read data.licenses.

ONLINE_INDEX_UNREACHABLE

(setup --dry-run) The online index could not be read, so the versions to install are unknown.

Check the network connectivity and retry.