> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI troubleshooting and current limits

> Resolve authentication, environment policy, repository, transfer, and live-execution errors.

# CLI troubleshooting and current limits

## `development environment is not enabled for CLI workloads`

Example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP 403: development environment is not enabled for CLI workloads
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient sandbox run --environment development -- pnpm test
```

This is a policy denial before sandbox creation.

## Profile is not logged in

Example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
profile "client-a" selected from project is not logged in
```

The nearest `.aient/config.yaml`, `AIENT_PROFILE`, or `--profile` selected a profile that has no local login:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth login --profile client-a
aient auth status --profile client-a
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth status
aient auth profiles
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient sandbox run \
  --environment development \
  --repository example/widget \
  -- pnpm test
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient --timeout 20m --verbose sandbox sync laptop-offload .
```

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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
printf "Paste execution UUID: "
IFS= read -r EXECUTION_ID
aient sandbox execution status \
  --environment development \
  --repository example/widget \
  laptop-offload "${EXECUTION_ID}"
aient sandbox execution attach \
  --environment development \
  --repository example/widget \
  laptop-offload "${EXECUTION_ID}"
```

`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](/ai-tools/cli/authentication). 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.