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

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, 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). 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.

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 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 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 for a first Project without a parent, and 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 first 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). 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).

Cancellation is settled but is not approval, and a later answer change does not fire the same wait again. See Sessions for notification meaning and version conditions, and 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 for ownership and 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, unresolved notes, or task blocks
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)
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.

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.

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)

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 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).

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).
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.

I want to see the logs

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

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

Authentication fails

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

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.

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:

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.

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.

Shared Documents are not syncing

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

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).

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 or mask 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. Workspace skills named aachat or aachat-asks are reserved repo-native surfaces and are intentionally masked from runtime discovery
5. 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
6. 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.

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 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).

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).

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).

When nothing above resolves it

Start interactive support.

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
• Agent repo structure and reflection timing: Agents
• Secrets and the environment variable mechanism: Environment
• Skill collisions: Skills — Sources of Truth and Improvement History
• Term definitions: Glossary