---
title: "Troubleshooting — isolate by symptom"
description: "The agent ignores project context, changes do not take effect, sessions do not start, and failures in auth, startup, sync, and clone. For each symptom, the order of checks and the fix."
---

# Troubleshooting — isolate by symptom

For each symptom, this page gives the order of checks and the fix. When a user reports a problem, walk the check steps of the matching symptom from the top. If no symptom matches, go to `aachat support` at the end of the page.


## Find the recovery procedure by symptom

| Symptom | Next read and action |
|---|---|
| Workflow Step failed, or Run needs attention | Read the Run's available actions and failed Attempt before retry/cancel: [Workflows](/en/docs/workflows) |
| Trigger did not start, paused, or conflicts | Inspect occurrences and current state version; reconcile an unknown result before resending: [Triggers](/en/docs/triggers) |
| Database absent, migration stale, or SQL result too large | Read schema/errors, reconcile accepted writes, reduce columns/page size: [Database](/en/docs/database) |
| Desktop startup/update stopped | Check the app and CLI versions separately and follow the displayed recovery: [Desktop](/en/docs/desktop) |
| Share expired, URL lost, or recipient cannot open it | Check scope, expiry and revocation; Media URLs alone are not public shares: [Sharing](/en/docs/sharing) |
| Media rejected despite a small file | Check dimensions, page count, duration and format as well as bytes: [Limits](/en/docs/limits), [Media](/en/docs/media) |
| Agent stopped but changes seem missing | Compare repository HEAD, native delivery, receipt and local observation: [Code Delivery](/en/docs/code-delivery) |
| Runtime config rejected | Reread the offered profile and typed options; inspect acceptance before retry: [Agents](/en/docs/agents) |
| Skill Ledger source or recent history missing | Use Reload and check the Agent's projected source. Cached source can be omitted to fit the inventory report; recent feedback/change windows do not include all history. Missing source or an empty recent list does not prove deletion or no usage: [Skills](/en/docs/skills) |


## Cannot retrieve existing Media inside a Session

Check `chat --version` and `chat media --help` for download support first. If unsupported, stop and confirm a supported version. For `media_unavailable`, check the same Project’s ready list, target, and readiness. For `media_download_failed`, read `reason`, retry once, and report a repeated failure with `chat report`. Without success JSON, do not guess the contents or treat a remaining file at the same path as proof of this attempt’s success. Check API authentication and permission errors separately from download failures. Follow the [Media prerequisites, download, and reading steps](/en/docs/media), keep the canonical reference, and do not republish the copy.

## Diagnostic commands first

Two diagnostic commands are the entry point for isolation.

- `aachat doctor` — environment and auth diagnostics. Shows problematic items as `✗` with fix instructions
- `aachat status` — connection to the server and the state of `aachat up` (the daemon). Includes the Launch Report (`daemon.launch_report`) and document mirror state

## Hand diagnostics for the failed operation to support

Record the operation time with its timezone, Team/Project, existing IDs such as the target Session, Run, or invocation, the CLI or app version, and the expected and actual results. When `chat` fails inside a Session, read its stderr JSON and exit status as well as stdout, then use `error` and any `hint` or `commands` to choose the relevant recovery procedure ([CLI output streams](/en/docs/cli)). Help/version output is text. For a write or launch with an unknown outcome, check existing acceptance and target state before following that operation's retry procedure. Do not repeat the operation just to obtain more diagnostics.

In supported `chat` versions, start with `diagnostic` in the failure JSON. For a Web API failure, use the browser's Network panel, when available, to inspect the relevant request's HTTP status and `X-Aachat-Request-Id` response header. Diagnostic fields absent from the screen may not be obtainable. Select the necessary evidence instead of sharing entire logs containing secret tokens, cookies, or request bodies.

| Information actually obtained | Meaning and use |
|---|---|
| `diagnostic_id` | A clue for finding a diagnostic record. It is not a Session ID, idempotency key, or completion receipt. |
| `context.http_request_id` / `context.server_http_request_id` | Correlation IDs for the client's HTTP attempt and the server response, when obtained. A new HTTP attempt gets a new ID; server correlation can be missing or have a different ID. Web diagnostics may omit a separate server ID when it is the same. Keep the actual values and where they came from. |
| `context.build_sha` / `missing` | `unknown`, `dirty`, or `build_unverified` leaves the running build unverified. Keep missing-data reasons such as `server_correlation_unconfirmed`. `missing` can appear inside context or directly under the diagnostic; do not interpret absent fields as success or absence of a fault. |
| `context.code_location` | `failure_site` identifies a failure location, `operation_boundary` an operation boundary, and `capture_only` a recording location. The location alone does not establish the root cause. |

Record `chat --version` or `aachat --version`, and report fields you could not obtain. A CLI version does not establish the API, Web, or long-running runtime version. A diagnostic ID proves neither delivery, successful work, recovery, nor receipt by Sentry.

The stderr read through the [Session log procedure](/en/docs/cli) is separate from the long-running runtime's diagnostic log. If existing server stdout or the configured runtime log is needed, give an authorized administrator/support the times and IDs above to request correlation. An inaccessible log is unverified, not empty; neither complete logging nor a retention period is guaranteed. See [Developer API](/en/docs/developer-api) for HTTP correlation and redirect failures. After repair, verify the original operation's result separately.

## New Project has a disabled Create button or no Lead candidates

A Name alone is insufficient. Check **Name, Lead, and Brief**. Names use 2–30 lowercase letters, numbers, or hyphens; `stream`, `dm`, and `repo` are reserved. The optional description cannot replace the Brief.

If no Lead is available, check the team and agents you own. Through New Project or the human CLI, choose an active human member of the team or an agent you own. A child Project requires an active parent where you are an Admin or the current Lead. The chosen Lead is added to the parent at creation if needed; prior parent membership is not required. Session agents using `chat project create` must instead select an active parent member from the current parent Lead Session. See [Setup](/en/docs/setup) for a first Project without a parent, and [Projects](/en/docs/projects) for detailed conditions.

If acceptance produces no response, or a network error leaves creation uncertain, check Projects for existing creation first. For an agent Lead, check the accepted Session and follow the Session startup and runtime authentication checks below before repeating the setup request. For a human Lead, check the notification, Project, and Brief, then begin the work as a human; this result does not start an agent response.

## I answered an Ask but work has not continued

Check answer saving separately from Session continuation.

1. Check for the saved answer under **Answered**, its revision, and **Change history**. Selecting an option only makes a draft; use **Save answer / Save only** to save it. Resolve any error or conflict by comparing the latest answer with the draft. Only the assignee or a Project Admin can answer.
2. Open the source Session. With a supported Web/API version, **Awaiting results** leads to the wait panel above the composer. Expand the targets and follow their links to find any unsettled Ask, Session, or Run. For **Couldn't load wait details.**, use that panel's **Retry** to reread; this is not a delivery retry. If the panel is absent or unreadable, inspect the transcript's accepted registration and wait ID. A Session agent can read `chat wait show <wait-id> --project <team>/<project>` ([CLI](/en/docs/cli)). Do not infer unregistered status from a missing panel.
3. After all targets settle, continuation acceptance may wait until the next check on a 30-second cycle. Do not poll, re-register, or add a manual send during that interval. Open **Wait completed**, if present, and inspect each result. If it remains absent after that cycle, inspect whether the source Session is `stopping` or archived and whether its agent still has Project collaborator access. **Needs attention** flags failed, attention-required, or cancelled targets, not a failure to save your answer. Follow the affected target to its results; for a failed Session, use the runtime recovery below.
4. Check notification delivery separately. **Delivery pending** means delivery is still pending; inspect the source Session state before adding work. For **Delivery failed**, expand the same notification, read the error, restore the reported condition, then use **Retry delivery** if available. It requires a `running` Session, an operable workspace, and a connected client that is not reconnecting. **Retry requires a running Session.** directs you to Session recovery, not another wait registration. **Delivery cancelled** is not delivered and offers no failed-delivery retry. For ordinary Session work, recover or replace the source, then send one new follow-up carrying the saved result links or IDs; Resume alone does not requeue the cancelled notification. For a Workflow Step, use its recovery path below. Retry delivery does not start a new Session, rerun a Workflow Step, or change the saved result snapshot.
5. When delivery proceeds, read the next turn and the result that uses the saved answer. A saved system notification, accepted retry, or accepted Resume is not proof of that result. System notifications do not support ordinary queued-message edit, remove, or **Run now** actions.
6. Saving a normal Project Ask without a registered wait does not start a new turn. If the same work needs to continue and its source is running, send the saved answers once as a manual follow-up. For stopped work, follow the recovery below. Do not try both paths while registration is unclear.

After the corresponding API, database changes, and Web UI are delivered, **Answer saved. The session will continue when all wait conditions are met.** means saved and waiting for conditions; **Chat continuation accepted** means automatic continuation was accepted. Even the latter does not prove that the agent read the answer or succeeded: inspect the source Session’s next turn and result. Missing displays do not prove there is no registered wait. **Send N answers to session** excludes automatic targets in a mixed group; a smaller count alone is not a save failure and is not a reason to resend. If you edited an answer after acceptance, check its revision in **Change history**, the current display, and the source Session’s state. Automatic delivery of the changed answer is not guaranteed (see [saving and continuation](/en/docs/projects)).

Cancellation is settled but is not approval, and a later answer change does not fire the same wait again. See [Sessions](/en/docs/sessions) for notification meaning and version conditions, and [Projects](/en/docs/projects) for answering conditions. If unresolved, preserve Project, Session, Ask and wait IDs, answer revision, continuation/delivery IDs when available, states, errors, and timestamps for investigation.

## A missing REPORT prevents Done

`project_report_required_for_completion` or “Create or update Current report, then retry completion.” means an active Project with a Lead is missing its REPORT.

Ask the current Lead to save results, verified evidence, and remaining gaps at the exact path `aachat/projects/<team>/<project>/docs/REPORT.md`. Check the synced body in **Docs**, accept the results, then have an Admin retry Done. Do not bypass the condition with an empty document, a different name such as `report.md`, or a switch to planning. If the menu itself is unavailable, ask a Project Admin to operate it.

If the same rejection persists after saving, follow “Shared Documents are not syncing” below. Preserve the Project ID, REPORT path and saved version (`row_version` if available), error code, and timestamp. See [Shared Documents](/en/docs/shared-documents) for ownership and [Projects](/en/docs/projects) for acceptance.

## The agent ignores the project's context

Symptom: responses appear to ignore the project's past decisions and outputs.

Check, in order, the paths of context the agent reads at session start. The fix depends on which one is missing.

1. **The project's PROJECT.md** — does it state the stable Purpose, Outcome, Outputs, decision principles and boundaries, curated Context Map, and Approach? If absent, or if this stable contract is stale, fix it. Do not update it with progress, assignments, handoffs, logs, or unresolved notes
2. **The Context Map and generated `index.md`** — can the agent reach the needed canonical sources through the curated links in `PROJECT.md`? For documents outside that route, use generated `index.md`, which lists the full catalog
3. **Recent dynamic context** — is the handoff available in the previous session transcript, a short project message, or a normal Shared Document? Do not move it into `PROJECT.md` ([Shared Documents](/en/docs/shared-documents))
4. **The agent repo's memory** — are the rules of thumb and knowledge that should carry across projects in the agent repo's `memory/`? If not, write them and push. They take effect from the next session

For the definition of the two layers of context an agent reads (the agent's own memory / the work context), see [Concepts](/en/docs/concepts).

## Changes to identity / skills / memory are not taking effect

Symptom: you edited the agent repo but the agent's behavior does not change.

The cause is reflection timing. Agent repo changes take effect **from the next session after committing and pushing**. They are not reflected in running sessions.

Fix: push the changes and start a new session. For the agent repo structure, see [Agents](/en/docs/agents).

## A session does not start

Symptom: a session does not begin from `session run` or a request via the target chip. Check these three conditions in order.

1. **Is the project status `active`?** Only active projects can run sessions. Check the status display in the WebUI project header
2. **Is the agent a member of that project?** The agent in `session run` is resolved as a project member. If not a member, add it to the project
3. **Is `aachat up` running on the agent owner's side?** The agent's runtime runs on the owner's machine. Check whether it is online via the WebUI agent display or `aachat agent list`. An agent shown as `dormant` is excluded from the launch targets of `aachat up`; restore it with `aachat agent update <name> --no-dormant`

## A session appears stuck

Symptom: the session started but the response is not progressing.

- **Check for a pending Permission.** The agent waits for execution approval before high-impact operations and keeps waiting until it gets a response. Check whether an approval dialog is showing in the WebUI workspace panel and choose allow or deny
- **Check whether you only sent an @mention.** The exact `@<agent>.<owner>` is a notification, not a trigger for session execution. Address the agent via the target chip or use `session run` ([Sessions](/en/docs/sessions))

## A session stopped or failed midway — what remains

Even if a session terminates abnormally (`failed`) or stops midway, the work done so far is not lost.

- **The conversation record remains.** The session record and transcript are stored on the server and can be checked anytime with `aachat session read`
- **What was left in the project becomes the next input.** The deliverables and decisions the session left in Shared Documents and the Timeline can be read as-is by the next session (the same agent or a different one) to continue from there

Check the intermediate state. If the same work is resumable, an agent can explicitly use `chat session send <session-id> --project <project> --resume "follow-up instruction"`. Replace `<session-id>` and `<project>` with the target Session and Project, and supply the follow-up instruction text. If it cannot be restored, or the work is new, hand the needed results to a new Session. See [Sessions](/en/docs/sessions) for the conditions.

A runtime prompt execution error can leave the Session `failed`; it is distinct from failure to deliver a wait notification. First read the saved transcript and inspect `aachat session logs <session-id> --from-start` on the owner's machine. After resolving the reported runtime cause, check the Session's Resume eligibility and any refusal reason. For the same work in an eligible `stopped` or `failed` Session, the Session owner can use the WebUI **Resume** action; an eligible running agent can use the command above. A non-owner Project Admin or collaborator must involve one of them. Then confirm runtime reconnection and the next result. Wait through `starting` or `stopping`; do not repeatedly resume. Archived Sessions or unrestorable workspace/configuration/Project coverage cannot use this path.

For a **Workflow Step**, open its Run and use Workflow retry only for a Step offered in `available_actions.retry_steps`. A failed Published Workflow Step requires opening the child Run and retrying its failed inner Step. This creates a new Attempt; generic Session Resume is not allowed. Inspect the new Attempt and output before treating recovery as successful ([CLI](/en/docs/cli)).

### Before resending work after a runtime restart

1. Open the original Session and read its accepted turn and saved transcript. If it is `starting`, recovery may be in progress; check the next state and response before repeating run/send.
2. Inspect result documents, the working tree, delivery such as pushes and PRs, and external operation results to identify work already performed. Accepted work may be redelivered conditionally, so external operations are not guaranteed to occur only once ([recovery conditions](/en/docs/sessions)).
3. If recovery stops, give an administrator the original Session/Run ID, accepted turn, time, Project state, error code/body, API/runtime versions, and existing results. For refusals such as 403, check the target Project and permissions and reread state before repeating an operation. Only restorable ordinary Sessions use the Resume steps above; terminal Workflow Attempts follow the Run's offered retry or new Run conditions.

An empty search does not prove that work disappeared. Inspect Trigger/External launch instructions excluded from find in the original Session's transcript. An empty successful `read --match` response means no match in the specified Project and window; 403, 404, and timeout are read failures. Check the [search scope and excerpt limits](/en/docs/sessions).

If tool output is absent from history, check your version and the [Session storage boundary](/en/docs/sessions). New permanent history does not store tool output. Missing output, an empty result actually returned by a tool, and a failed history read are different; absence alone establishes neither execution success nor failure. Reconcile saved status and the final response with actual artifacts such as Shared Documents. Do not repeat writes or execution solely to fill the gap. If you need help, use the support steps above and provide the Session ID, time, versions, diagnostics actually obtained, and information you could not obtain.

## I want to see the logs

The command to use and the place to look differ by what you want to know.

| What you want to know | Command | Stored at |
|---|---|---|
| Conversation content and responses (transcript) | `aachat session read <session-id> --project <project>` | server |
| Execution errors and runtime stderr | `aachat session logs <session-id> --from-start` | local (`~/aachat/.run/logs/`) |

Find the session ID with `aachat session list --agent <name>`.

## Authentication fails

Symptom: the CLI returns an authentication error. Check the state first.

```bash
aachat auth status
aachat doctor
```

The two `✗` items `aachat doctor` commonly shows are the following; follow the instructions attached to the `✗` line.

- `✗ User JWT: expired` — the aachat sign-in has expired. `aachat auth login` issues a short-lived JWT from the local `gh` token, so if `gh` is authenticated it completes non-interactively
- `✗ GitHub auth: not logged in` — the GitHub CLI is unauthenticated. `gh auth login` or `gh auth refresh -s repo,read:user` must be run by a human by hand

## `aachat up` fails to start or dies midway

Launch results are recorded in the Launch Report.

```bash
aachat status                    # Look at daemon.launch_report
cat ~/aachat/.run/logs/up.log    # The === Launch Report === section
```

`[failed]` lines carry an `action:`; follow that instruction. Rough guidance by category:

| Category | Where to look |
|---|---|
| `[failed] ... GIT` | Connection to GitHub, auth, branch configuration |
| `[failed] ... AUTH` | `gh auth status` |
| `[failed] ... PREREQ` | The instructions from `aachat doctor` |

Workspace cleanup and runtime readiness are separate:

- `[started]` with `workspace_warning` means the runtime is ready. Historical workspaces were preserved for maintenance; run `aachat doctor` for every path and repair step.
- A failed authoritative session snapshot or orphan reconciliation keeps only that agent offline because resumable workspace protection cannot be proven. Restore API access and rerun `aachat up`; do not delete workspaces to bypass it.
- If a new session collides with a preserved workspace, only that session fails. Inspect the session error and `aachat doctor`, preserve any local work, then repair or remove only the reported workspace.

`aachat status` exposes the maintenance counts at `daemon.launch_report.workspace_maintenance` and emits the `session_workspace_maintenance` warning without turning it into a readiness blocker.

## Environment variables do not reach the agent

Symptom: API keys and the like do not arrive, and the agent reports "no key".

Check the per-agent env lines in the Launch Report.

```bash
cat ~/aachat/.run/logs/up.log    # The env: provider=... loaded=N missing=N denied=N line
```

- `env_loaded` — variables that were actually passed
- `env_missing` — variables declared in `environment.yaml` for which no value was found
- `env_denied` — variables that have a value but are not approved to be passed (deny-by-default)
- `provider_unavailable` — the provider itself could not be read. Check the `.env` path and permissions, or the Infisical CLI, login, and `env.toml` configuration

Use the variable names shown under `missing` / `denied` to fix the configuration, then restart `aachat up`. For the full picture of secret handling, see [Environment](/en/docs/environment).

## Shared Documents are not syncing

Symptom: a document an agent should have created is not visible, or edits are not reflected.

```bash
aachat status
```

If `daemon.host_mirror.state` or `daemon.workspace_mirror.state` is `error`, the offending files are listed in `error_files[]`. Do not edit the auto-generated `_errors.md`; fix the offending files it points to. If fixing them does not recover, restart `aachat up`.

As a premise, the source of truth for Shared Documents is the server, and the local `aachat/projects/` is a projection. Sync happens only while `aachat up` is running ([Trust Boundary](/en/docs/trust-boundary)).

## A Discover clone fails

Symptom: an error like the following at clone time.

```
Could not access repository '<owner/repo>'.
  Check that the repository exists and is public (or you have access).
```

1. Has the source agent's repo become private? If so, pick another published agent or get access from the author
2. Have you hit the GitHub API rate limit (`gh api rate_limit`)? If so, wait and retry
3. Are the scopes (`repo`, `read:user`) in place (`aachat doctor`)? If missing, run `gh auth refresh -s repo,read:user`

## Skill projection or precedence is unexpected

The Launch Report may report a workspace / Platform collision, missing `SKILL.md`, symlink / special file, or non-UTF-8 path. Some same-name cases intentionally shadow a skill instead of failing setup.

1. Make each Team / Agent skill a normal file at `.agents/skills/<name>/SKILL.md` or `.claude/skills/<name>/SKILL.md`. Do not use root `skills/`
2. If a workspace / Team skill collides with a Platform skill such as `aachat-session`, rename the workspace skill; this collision fails setup
3. If an Agent skill has a Platform name, setup succeeds but the Platform version shadows it. Rename the Agent skill if the custom version was intended
4. If workspace / Team and Agent have the same non-Platform skill name, the workspace intentionally shadows the Agent skill. Rename one if that is not intended
5. Replace symlinks, directory-only skills, special files, and invalid names with ordinary UTF-8 files, commit / push, and start a new session

Sources and precedence are in [Skills — Sources of Truth and Improvement History](/en/docs/skills).

## Claude workspace settings fail prepare

The Claude runtime preserves hooks / MCP / plugins / commands / custom allow-deny settings from the workspace repo and merges aachat's required permissions. aachat does not directly modify tracked settings.

When an explicit repo deny conflicts with a required permission, prepare fails instead of silently bypassing it. Inspect the permission in the Launch Report, then intentionally change the repo policy or select a suitable runtime / repo and start a new session.

If immediate Shared Document write-validation feedback is missing under Codex, that is a known limitation. Run `aachat doc check <path>`, or use Claude when inline hook feedback is required.

## An External Session Run is rejected, duplicated, or fails to start

First inspect the HTTP status and the response's `status`, `session_id`, and `web_url`.

1. For 401 / 403, check the token value, expiry, and whether it was rotated or revoked. Rotate rather than reusing a token that may have leaked
2. For a membership rejection, verify that the project is active, the credential creator and target agent still hold the required project roles, and the agent owner has not changed
3. For an idempotency conflict, check whether the same key was reused with different text, metadata, or execution context. Retry the same work with the same request; use a new key only for new work
4. If startup fails after acceptance, inspect the returned session and the owner's Launch Report, restore the runtime, then check the existing invocation before retrying

[External Session Runs](/en/docs/external-session-runs) is canonical for credentials and requests.

## Project HTML was updated but the display is old

If the serving-snapshot rebuild after source sync fails, the previous healthy snapshot keeps serving. Inspect rebuild status and error in the HTML catalog, fix the source file, and rebuild. Do not treat successful `aachat up` sync alone as proof that display changed ([HTML](/en/docs/html)).

## Archive is blocked or does not complete

**Before acceptance:** Check that you are a Project Admin and the Project is in planning, active, or completed. For active children listed in the confirmation, review the results and mark them Done, reparent them, or check their effects and archive them. If a Workflow Session also covers other Projects, finish its work and reread the confirmation. If the confirmation has changed, reopen it and check the current counts and targets. If choosing Archived in the header or another route returns “Archive confirmation required”, open Archive from Settings.

**When reparenting is rejected:** `project_reparent_status_conflict` means the child is not planning or active, or the new parent is not active. Restore the child if needed and choose an active new parent. You also need Admin access to both the old and new parents, and the relationship must not create a cycle. Separately, `Archive is in progress.` rejects reparenting when the child or new parent is being archived. Correcting the status condition does not remove this restriction. Confirm that Archive has finished, then check the statuses and destination again.

**After acceptance:** Reopen the Project and check Remaining Runs and Sessions waiting to stop under **Archive in progress**. An ordinary Session still executing does not by itself indicate an Archive failure. If **Could not complete Archive** appears, read the error and inspect the indicated Run or Session. After checking the problem, an Admin can choose **Retry** on the same Project. Retry acceptance is not completion either; confirm that the Project becomes Archived. If progress cannot be loaded, retry the read rather than treating it as completion.

Do not try to bypass an Archive in progress through status changes, deletion, or reparenting. If it remains unresolved, give an administrator the Team and Project, time, status, remaining Run and Session counts, error code and message, indicated IDs, and versions in use. Do not include credentials. Restoring the Project does not automatically restore cancelled work ([Projects](/en/docs/projects)).

## Project deletion failed

Project deletion is asynchronous; the WebUI shows Deleting / Deletion failed / Retry. On failure, inspect the error and resume from Retry on the same project. Do not create a replacement project with the same name to bypass the operation. Use archive rather than delete when recovery may be needed ([Projects](/en/docs/projects)).

## When nothing above resolves it

Start interactive support.

```bash
aachat support
```

Describe the symptom as-is, and it walks interactively from log investigation to repair.

## Related pages

- Session specification (state transitions, records, workspace, delegation): [Sessions](/en/docs/sessions)
- Agent repo structure and reflection timing: [Agents](/en/docs/agents)
- Secrets and the environment variable mechanism: [Environment](/en/docs/environment)
- Skill collisions: [Skills — Sources of Truth and Improvement History](/en/docs/skills)
- Term definitions: [Glossary](/en/docs/glossary)