Troubleshooting

The Stack Does Not Start

1. Run bun run stack config.
2. Confirm every tracked placeholder was replaced in local-stack.json.
3. Check configured host ports.
4. Run bun run stack ps.
5. Read logs for the first unhealthy dependency rather than the last service that failed.

Migrations Fail

Confirm PostgreSQL is healthy, the configured credentials match the generated environment, and the migration service can reach the Compose database name. Do not add migration retry loops to normal application startup.

Chat Does Not Respond

Check backend and chat-runtime health. A pending response should be recoverable after a missed live signal, so avoid repeatedly submitting the same request while services restart.

A Task Does Not Run

Check whether it is due, dependency-ready, within attempt limits, unblocked, and free of conflicting active work. Inspect the latest attempt and Human Inbox before creating a replacement task.

Onboarding Cannot Continue

Confirm the organization and every selected department have at least one source. Check extension, size, filename length, UTF-8 encoding, and PDF text-layer requirements.

Context Looks Incomplete

Inspect sources and evidence status. Add or promote a current source rather than repeating an unsupported claim in chat. Run the context audit when broad health needs reevaluation.

An Integration Is Not Ready

• Confirm the credential or OAuth connection.
• Check selected tools or services.
• Check profile grants.
• Verify read-only annotations for MCP reads.
• Rotate or reconnect only after identifying the actual failing boundary.

A Write Requires Approval

Resolve the Approval item. Do not resubmit the effect with a new idempotency key.

An Action Requires Reconciliation

Check the provider directly, then record whether the effect succeeded or failed. Never retry an unknown external effect before verification.

Last Resort Reset

Use bun run stack reset --confirm only when losing all local stack state is acceptable. Reset is not a normal response to an invalid configuration, unavailable provider, or blocked task.