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

## 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

## 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 project's purpose and premises? If absent or stale, fixing it is the first remedy
2. **The latest handoff document** — are the previous session's outputs, decisions, and open items left in Shared Documents as a handoff? If not, correct the practice so a handoff is left at the end of each session (`shared-documents.md`)
3. **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.md`.

## 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.md`.

## 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.** `@<agent>` is a notification, not a trigger for session execution. Address the agent via the target chip or use `session run` (`sessions.md`)

## 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

The basic recovery procedure is to check the intermediate state and ask a new session to continue.

## 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` |

## 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.md`.

## 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.md`).

## 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`

## 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.md`
- Agent repo structure and reflection timing: `agents.md`
- Secrets and the environment variable mechanism: `environment.md`
- Term definitions: `glossary.md`