Troubleshooting

The Installer Stops Early

• Confirm the host is macOS or Linux on AMD64 or ARM64.
• Run docker info and docker compose version.
• For local auth, run codex login status, then codex login when needed.
• For API-key auth, export the variable configured in local-stack.json.
• Check access to downloads.oblive.dev and Amazon ECR Public.
• Rerun the same installer command. Existing configuration is preserved.

The installer verifies the release checksum and rejects unsafe archive paths, links, corrupt downloads, unstable versions, and an unrelated file already occupying the CLI path.

The Stack Does Not Start

1. Run oblive doctor.
2. Run oblive config check.
3. Check configured host ports in oblive config edit.
4. Run oblive status.
5. Read logs for the first unhealthy dependency rather than the last service that failed.

If you are developing from source, use the equivalent bun run stack config, ps, and logs commands from the developer guide.

Codex Authentication Fails

For local mode:

oblive auth status
oblive auth login
oblive restart --no-open

Only auth.json is synchronized. An invalid host Codex configuration can also prevent the Codex CLI from reporting login status; correct that configuration with Codex before retrying.

For API-key mode, ensure the configured environment variable is exported in the shell that runs oblive start.

Migrations Fail

Confirm PostgreSQL is healthy, the configured credentials are valid, and the migration service can reach the Compose database. Do not reset data merely because a migration failed. Read migration logs first:

oblive logs migrate
oblive logs postgres

An Update Fails

oblive update preflights the new bundle before switching. If startup fails after migrations may have run, it leaves the new release installed and reports the retained previous files rather than automatically downgrading the database.

Check oblive status and service logs. Do not manually replace the installation with an older release; restore a compatible data backup when a rollback is required.

Chat Does Not Respond

Check backend and agent-chat logs. A pending response should be recoverable after a missed live signal: the scheduler republishes pending responses without interrupting running ones. Confirm the scheduler is enabled if a response stays pending. Confirmed onboarding findings automatically wake the setup chat after their continuation is committed. Avoid repeatedly submitting the same request while services recover.

If a response fails because the model requires a newer Codex version, rebuild the agent images with the release’s locked SDK dependency; restarting an old image does not update its binary. Non-fatal provider diagnostics do not stop responses. A missing saved Codex session is recovered once, before any item event, using a fresh session with the backend-provided conversation context. Terminal failures remain visible; after the runtime is repaired, send another message to continue.

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

Stop and resume are built-in Work controls, not onboarding facts. An obsolete emergency-stop field in early v4 Context files is ignored and removed when the file is rendered.

Check discovery status and unresolved questions. Website evidence and credible retained public sources can support claims directly; uploading the same information again is unnecessary. For an uploaded file that failed processing, check its extension, size, encoding, and PDF text layer.

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

Last Resort Reset

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