Skip to main content

​
CLI troubleshooting and current limits

​
development environment is not enabled for CLI workloads

Example:
The selected environment exists, but its administrator has not allowed authenticated customer CLI workspaces to use its sandbox-exportable development capabilities. Ask an organisation administrator to open the environment’s Sandbox settings and enable customer CLI development. Then repeat the command with that environment’s actual slug:
This is a policy denial before sandbox creation.

​
Profile is not logged in

Example:
The nearest .aient/config.yaml, AIENT_PROFILE, or --profile selected a profile that has no local login:
Use aient auth profiles to inspect local profile names.

​
Project organisation mismatch

The organisation in .aient/config.yaml is an assertion. If OAuth resolves another organisation, Aient fails before sandbox creation. Check the selected profile:
Then correct the non-secret project selector or log into the intended profile. Do not remove the assertion merely to force execution against the wrong customer context.

​
Repository is absent or ambiguous

A local Git remote is only a selector. If no authorised repository matches, ordinary workspace offload may continue with GitHub access: none. Provider operations such as branch push and gh pr create require verified repository authority. When more than one remote is plausible, disambiguate:
Changing origin cannot grant access to another organisation’s private repository.

​
sandbox_allocation_terms_conflict

Aient CLI 0.11.29 reports this HTTP 409 error when a sandbox name already has an allocation with a different size, CPU, memory, or environment. The allocation can belong to a live sandbox or a creation attempt refused in the last few minutes. The failed request creates nothing. Retry with the original options, choose another --name, or delete the existing sandbox before recreating it if you no longer need its contents. Repeating the conflicting request unchanged will not resolve the error.

​
workspace busy

An admitted command or workspace read holds the shared workspace fence, while sync and file mutations require exclusive access.
  • Wait for the current execution with sandbox execution wait, repeating its original environment and repository selectors.
  • Avoid starting multiple syncs or direct workspace mutations.
  • Retry only after the known reader or mutation finishes.
The CLI never replays an arbitrary command that may already have started.

​
Transfer shows progress but the workspace is absent

A line such as Transferred workspace archive: 56.0 MiB / 448.4 MiB is progress, not completion. Successful sync ends with an explicit Synchronized ... line and a terminal process result. If you invoke aient from an agent, build tool, or wrapper:
  • preserve the child result object, including a running session handle;
  • continue polling that exact handle until a terminal exit status;
  • keep draining stdout and stderr;
  • do not treat completion of the outer wrapper as completion of the CLI; and
  • do not mutate the target workspace while the upload is active.
Since Aient CLI 0.8.2, sandbox sync resets its timeout while upload bytes continue to flow and when the server begins responding. If a current transfer fails despite continuing progress, check aient version; releases before 0.8.2 applied the default five-minute budget to the whole HTTP request. For an unusually slow connection, increase the permitted inactivity gap:
Reuse an environment-bound customer sandbox with sandbox sync SANDBOX . --environment ENV --repository OWNER/REPO, repeating its original selectors. An interrupted upload does not continue from its last reported byte. Inspect and recover the retained workspace operation. Eligible native V3 Git-cache recovery in 0.11.22 preserves the original captured files, including when later local edits exist.

​
Connection ended during sandbox exec

sandbox exec prints the execution ID before dispatch and performs bounded transport recovery for that same execution. If the client still loses its connection:
Use attach --after-cursor CURSOR to replay supervisor-retained output after the last accepted cursor, then follow live output. Retention is bounded. Use execution wait when you need only the terminal outcome. If you see output incomplete or exit status 74, follow the incomplete-output guidance.

​
Portable access token expired

Imported access-only credentials are never refreshed. Export another from a refresh-backed profile or log in on the target machine: Use the unique temporary-directory and cleanup pattern in Authentication and project profiles. Delete the old access-only file. Do not copy refresh tokens or keychain data.

​
A retained customer sandbox rejects sync, files, or shell

An environment-bound sandbox created with sandbox run --environment ... --keep requires the original environment and repository selectors on later sync, exec, and execution operations. status, wait, and logs require the original --environment selector. Upgrade an older CLI before retrying sync. files and shell cannot address an environment-bound sandbox.

​
Current unsupported behaviour

  • sandbox shell cannot reattach and has no history replay.
  • Interactive shells cannot request environment or repository capabilities.
  • Environment-bound customer sandboxes cannot use files or shell.
  • files get downloads a file, not a directory.
For other failures, rerun with --verbose. It prints safe correlation metadata without printing OAuth, environment, or provider credentials.