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:

Run with --verbose debug to see the per-bundle error details.
For project deploy commands, inspect data.bundles[].error.code when the command returns a partial success, or error.details.failedBundles when all bundles failed.
For machine-bootstrap or setup, inspect data.results[] on partial success, or error.details.results when all bundles failed.
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:

Check network connectivity.
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.
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:

Inspect project lock state with cube agentic-ai project-lock-show <project> and identify the required bundle version.
Install the missing version (cube bundle install <bundle>@<version>), then rerun the command.
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:

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).
Reconcile the bundle references into the shared .settings/bundles.store.json (or remove the legacy folder if its references are already reflected there).
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:

The file may have syntax errors (missing commas, unescaped quotes, invalid comments).
Check the file path in the error details for the exact location.
For VS Code workspace manifests (.vscode/mcp.json), ensure the server map is valid JSON under top-level servers.
If you copied a settings.json-style wrapper ({"mcp":{"servers":...}}) into .vscode/mcp.json, rewrite it as top-level servers.
Fix the JSON syntax and retry, or delete the file to reset it.
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:

Ensure both the bundle MCP file and project MCP manifest use the same file format.
Ensure the MCP payload contains a recognized server map: servers, mcpServers, or mcp.servers.
When the project MCP manifest already exists, the installer preserves that existing key path and merges bundle servers into it.
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).
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:

This protects your project from losing custom server configurations.
A sidecar file (mcp-st<ext>) has been created next to your project’s MCP manifest.
Manually merge the two files, keeping the configuration that is correct for your project.
Delete the sidecar file after merging.
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:

Provide a preset file with --preset <config_file> when using --preset-no-reconcile.
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:

Re-run with --verbose debug and inspect failedPath, deletedPaths, and pendingPaths in error details.
Resolve the failing path condition (permissions, file lock, path state).
Re-run project-remove.
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:

Re-run with --verbose debug to inspect the computed removal paths.
Check whether files were moved after deployment (especially after --canonical runs).
Move files back to the expected managed paths.
Re-run project-remove.

`PROJECT_REMOVE_PERMISSION_PRECHECK_FAILED` ¶

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

Action:

Re-run with --verbose debug and inspect the failing path details.
Check file and directory permissions/ACLs for the managed targets.
Close processes that may lock files.
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.

`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:

Treat the lock state as potentially stale.
Inspect current project files and compare with lock content.
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:

Re-run with --verbose debug and capture stdout/stderr.
If the error is one of CATALOG_NOT_FOUND, CATALOG_PARSE_ERROR, or CATALOG_INVALID, follow the catalog-specific action above.
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:

Check details.targetType in the error JSON (ide or agenticSystem) to know which dimension failed.
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

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.

`USER_JOURNEY_SCHEMA_UNSUPPORTED` ¶

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

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.

Troubleshooting ¶

Diagnostics and tips ¶

Error codes ¶

ADVISORY_ONLY ¶

ALL_BUNDLES_FAILED ¶

ARTIFACT_DUPLICATE_DESTINATION ¶

ARTIFACT_USER_OWNED_CONFLICT ¶

ARTIFACT_CONNECTOR_SERVICE_CONFLICT ¶

ARTIFACT_CROSS_CONNECTOR_CONFLICT ¶

ARTIFACT_CONTENT_HASH_MISMATCH ¶

SERVICES_LOCK_SCHEMA_UNSUPPORTED ¶

PROJECT_REMOVE_REQUIRED_SERVICE_CONFIRMATION_REQUIRED ¶

ARTIFACT_ENTRYPOINT_MISSING ¶

ARTIFACT_METADATA_INVALID ¶

ARTIFACT_KIND_UNDEFINED ¶

ARTIFACT_NAME_INVALID ¶

ARTIFACT_REFERENCE_KIND_MISMATCH ¶

ARTIFACT_REFERENCE_MISSING ¶

ARTIFACT_REFERENCE_UNKNOWN ¶

ARTIFACT_RESOURCE_OWNS_RESOURCE ¶

BUNDLE_INSTALL_FAILED ¶

BUNDLE_LOCKED_VERSION_NOT_INSTALLED ¶

BUNDLE_NOT_DEPLOYED ¶

BUNDLE_NOT_FOUND ¶

BUNDLE_NOT_IN_AI_CATALOG ¶

CATALOG_INVALID ¶

CATALOG_NOT_FOUND ¶

CATALOG_PARSE_ERROR ¶

CATALOG_VALIDATION_FAILED ¶

CUBE_BUNDLE_INFO_ERROR ¶

CUBE_LIST_ERROR ¶

CUBE_NOT_FOUND ¶

INVALID_OPTION_COMBINATION ¶

INVALID_USAGE ¶

JSON_FILE_WRITE_FAILED ¶

LEGACY_CUBE_PROJECT_LOCK_UNSUPPORTED ¶

LIST_SUPPORTED_TARGETS_FAILED ¶

LOCK_READ_ERROR ¶

MACHINE_DISCOVERY_FAILED ¶

MANUAL_NOT_FOUND ¶

MCP_CONFIG_PARSE_FAILED ¶

MCP_FORMAT_INCOMPATIBLE ¶

MCP_MERGE_CONFLICT ¶

MCP_SERIALIZATION_FAILED ¶

NO_SUPPORTED_TARGET ¶

PATH_TRAVERSAL_DETECTED ¶

PRESET_INVALID ¶

PRESET_NOT_FOUND ¶

PROJECT_DEPLOY_INVALID_OPTIONS ¶

PROJECT_NOT_FOUND ¶

PROJECT_REMOVE_FAILED ¶

PROJECT_REMOVE_IO_FAILED ¶

PROJECT_REMOVE_MANAGED_PATHS_MISSING ¶

PROJECT_REMOVE_PERMISSION_PRECHECK_FAILED ¶

ROUTING_SECOND_CHOICE_POLICY_INVALID ¶

ROUTING_SECOND_CHOICE_SCHEMA_UNSUPPORTED ¶

SERVICES_LOCK_UNRELIABLE_WRITE_FAILED ¶

SERVICES_SCHEMA_UNSUPPORTED ¶

SERVICES_VALIDATION_FAILED ¶

SHOW_CATALOG_FAILED ¶

TARGET_AMBIGUOUS ¶

TARGET_CHANGED_IN_DEPLOYED_PROJECT ¶

TARGET_COMBINATION_NOT_SUPPORTED ¶

TARGET_NOT_DETECTED ¶

TARGET_PROFILE_UNSUPPORTED ¶

USER_JOURNEY_POLICY_INVALID ¶

USER_JOURNEY_SCHEMA_UNSUPPORTED ¶

Codes of setup and doctor ¶

VS Code extension repair failures ¶

CONTEXTS_EMPTY ¶

CONTEXT_REQUIRES_VSCODE ¶

BUNDLE_IDE_NOT_SUPPORTED ¶

INVALID_PYTHON_CHOICE ¶

INVALID_VSCODE_PROFILE_NAME ¶

PROJECT_FOLDER_UNSAFE ¶

PROJECT_FOLDER_CREATE_FAILED ¶

SETUP_PROJECT_ALREADY_DEPLOYED ¶

SETUP_FAILED and DOCTOR_FAILED ¶

Warnings of setup and doctor ¶

`ADVISORY_ONLY` ¶

`ALL_BUNDLES_FAILED` ¶

`ARTIFACT_DUPLICATE_DESTINATION` ¶

`ARTIFACT_USER_OWNED_CONFLICT` ¶

`ARTIFACT_CONNECTOR_SERVICE_CONFLICT` ¶

`ARTIFACT_CROSS_CONNECTOR_CONFLICT` ¶

`ARTIFACT_CONTENT_HASH_MISMATCH` ¶

`SERVICES_LOCK_SCHEMA_UNSUPPORTED` ¶

`PROJECT_REMOVE_REQUIRED_SERVICE_CONFIRMATION_REQUIRED` ¶

`ARTIFACT_ENTRYPOINT_MISSING` ¶

`ARTIFACT_METADATA_INVALID` ¶

`ARTIFACT_KIND_UNDEFINED` ¶

`ARTIFACT_NAME_INVALID` ¶

`ARTIFACT_REFERENCE_KIND_MISMATCH` ¶

`ARTIFACT_REFERENCE_MISSING` ¶

`ARTIFACT_REFERENCE_UNKNOWN` ¶

`ARTIFACT_RESOURCE_OWNS_RESOURCE` ¶

`BUNDLE_INSTALL_FAILED` ¶

`BUNDLE_LOCKED_VERSION_NOT_INSTALLED` ¶

`BUNDLE_NOT_DEPLOYED` ¶

`BUNDLE_NOT_FOUND` ¶

`BUNDLE_NOT_IN_AI_CATALOG` ¶

`CATALOG_INVALID` ¶

`CATALOG_NOT_FOUND` ¶

`CATALOG_PARSE_ERROR` ¶

`CATALOG_VALIDATION_FAILED` ¶

`CUBE_BUNDLE_INFO_ERROR` ¶

`CUBE_LIST_ERROR` ¶

`CUBE_NOT_FOUND` ¶

`INVALID_OPTION_COMBINATION` ¶

`INVALID_USAGE` ¶

`JSON_FILE_WRITE_FAILED` ¶

`LEGACY_CUBE_PROJECT_LOCK_UNSUPPORTED` ¶

`LIST_SUPPORTED_TARGETS_FAILED` ¶

`LOCK_READ_ERROR` ¶

`MACHINE_DISCOVERY_FAILED` ¶

`MANUAL_NOT_FOUND` ¶

`MCP_CONFIG_PARSE_FAILED` ¶

`MCP_FORMAT_INCOMPATIBLE` ¶

`MCP_MERGE_CONFLICT` ¶

`MCP_SERIALIZATION_FAILED` ¶

`NO_SUPPORTED_TARGET` ¶

`PATH_TRAVERSAL_DETECTED` ¶

`PRESET_INVALID` ¶

`PRESET_NOT_FOUND` ¶

`PROJECT_DEPLOY_INVALID_OPTIONS` ¶

`PROJECT_NOT_FOUND` ¶

`PROJECT_REMOVE_FAILED` ¶

`PROJECT_REMOVE_IO_FAILED` ¶

`PROJECT_REMOVE_MANAGED_PATHS_MISSING` ¶

`PROJECT_REMOVE_PERMISSION_PRECHECK_FAILED` ¶

`ROUTING_SECOND_CHOICE_POLICY_INVALID` ¶

`ROUTING_SECOND_CHOICE_SCHEMA_UNSUPPORTED` ¶

`SERVICES_LOCK_UNRELIABLE_WRITE_FAILED` ¶

`SERVICES_SCHEMA_UNSUPPORTED` ¶

`SERVICES_VALIDATION_FAILED` ¶

`SHOW_CATALOG_FAILED` ¶

`TARGET_AMBIGUOUS` ¶

`TARGET_CHANGED_IN_DEPLOYED_PROJECT` ¶

`TARGET_COMBINATION_NOT_SUPPORTED` ¶

`TARGET_NOT_DETECTED` ¶

`TARGET_PROFILE_UNSUPPORTED` ¶

`USER_JOURNEY_POLICY_INVALID` ¶

`USER_JOURNEY_SCHEMA_UNSUPPORTED` ¶

Codes of `setup` and `doctor` ¶

`CONTEXTS_EMPTY` ¶

`CONTEXT_REQUIRES_VSCODE` ¶

`BUNDLE_IDE_NOT_SUPPORTED` ¶

`INVALID_PYTHON_CHOICE` ¶

`INVALID_VSCODE_PROFILE_NAME` ¶

`PROJECT_FOLDER_UNSAFE` ¶

`PROJECT_FOLDER_CREATE_FAILED` ¶

`SETUP_PROJECT_ALREADY_DEPLOYED` ¶

`SETUP_FAILED` and `DOCTOR_FAILED` ¶

Warnings of `setup` and `doctor` ¶