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.

​
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.
For a large sandbox without an environment binding:
An environment-bound customer should start a fresh sandbox run --environment ... --keep to transfer changed workspace state in 0.7.0.

​
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:
attach receives only future live output. There is no stored stdout/stderr history. Use execution wait when you need only the terminal outcome.

​
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, shell, or status

An environment-bound sandbox created with sandbox run --environment ... --keep requires the original authority selectors on later exec and execution operations. In 0.7.0, only those selector-bearing operations, list --environment, and owner delete support the bound customer contract. sync, files, shell, status, wait, and logs cannot address the sandbox. Start a fresh run --keep when local workspace state changes.

​
Current unsupported behaviour

  • Commands cannot deliberately detach.
  • Execution output is live-only and cannot be replayed.
  • sandbox shell cannot reattach and has no history replay.
  • Interactive shells cannot request environment or repository capabilities.
  • Environment-bound customer sandboxes cannot use sync, files, shell, status, wait, or logs.
  • 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.