Troubleshooting

Each recovery starts with a non-mutating inspection. Run argus for the guided menu or use the direct commands below. Omit --json for readable terminal output; keep it when collecting a structured report for automation or support. Run a --dry-run plan before every CLI mutation that supports it, then add --yes only after reviewing the current plan. Stable error codes below are the CLI or doctor codes to retain when escalating. Use argus logs --raw only when the compact log view leaves out detail you need.

# Readable first look
argus status
argus logs argus --tail 200
argus doctor

# Readable example plan; this does not change the instance
argus config apply /opt/argus/argus.yaml --dry-run

Installer failure

Inspect: ARGUS_INSTALL_INSPECT=1 sh /tmp/argus-install.sh after downloading the installer with curl -fsSLo /tmp/argus-install.sh https://argus.gpsxtre.me/install.sh.

Meaning: A bad Ed25519 signature, malformed manifest, or wrapper hash mismatch stops installation before the wrapper is replaced. Host prerequisite failures are reported before onboarding as PREFLIGHT_FAILED with individual preflight codes.

Recover: Review the no-change inspection output, correct the reported host or release-distribution problem, then explicitly rerun sh /tmp/argus-install.sh. The installer has an inspection mode, not an Argus --dry-run flag.

Docker unavailable

Inspect: argus doctor --json.

Meaning: DOCKER_UNAVAILABLE means the management container cannot reach Docker. During onboarding, DOCKER_NOT_INSTALLED, DOCKER_COMPOSE_UNAVAILABLE, or DOCKER_DAEMON_UNREACHABLE identifies the prerequisite.

Recover: Start Docker, install the Compose plugin, or grant the operating user daemon access as the reported prerequisite requires. For a pending onboarding, keep non-secret answers in a safely permissioned file, run argus onboard --from /path/to/answers.yaml --dry-run --json, review its plan, then run argus onboard --from /path/to/answers.yaml --yes --json from a TTY to enter any required secrets through hidden prompts. For an existing instance, rerun argus doctor --json.

Service is unhealthy or degraded

Inspect: argus status --json, then argus logs argus --tail 200 --json and argus doctor --json.

Meaning: degraded means at least one selected Compose service is not healthy. ARGUS_HEALTHCHECK_FAILED, STORAGE_HEALTHCHECK_FAILED, or DOCKER_UNAVAILABLE identifies the failed health category.

Recover: For the managed Argus service, run argus repair argus --dry-run --json, then argus repair argus --yes --json; finish with argus doctor --json. For a database or SearXNG finding, use only its matching supported repair below.

Configuration is rejected

Inspect: argus config validate /opt/argus/argus.yaml --json and argus config show /opt/argus/argus.yaml --json.

Meaning: Invalid YAML, schema, missing secret reference, or unsafe secret file prevents a valid configuration plan. A stale inspected plan is CONFIG_SERVICE_PLAN_STALE; missing live integration is INSTALLED_CONFIG_INTEGRATION_REQUIRED.

Recover: Correct the non-secret YAML or set the missing secret, run argus config apply /opt/argus/argus.yaml --dry-run --json, then argus config apply /opt/argus/argus.yaml --yes --json.

Argus v2 intentionally rejects version: 1, unversioned databases, and old table layouts before mutation. There is no compatibility migration. Point v2 at an empty SQLite file or PostgreSQL database and ingest fresh data.

A source yields no records

Inspect: argus doctor --json and argus logs argus --tail 200 --json.

Meaning: SOURCE_DIAGNOSTIC_TARGET_NOT_CONFIGURED means doctor has no enabled configured target to smoke-test. SOURCE_SMOKE_FAILED or SOURCE_SMOKE_TIMEOUT means the temporary isolated source check did not ingest its target; SOURCE_SMOKE_CLEANUP_FAILED means its temporary watch was not removed.

Recover: Correct the enabled source, target, or schedule in YAML, then run argus config apply /opt/argus/argus.yaml --dry-run --json followed by argus config apply /opt/argus/argus.yaml --yes --json. Do not use doctor diagnostic records as ordinary watch records.

SearXNG is unavailable

Inspect: argus doctor --json and argus logs searxng --tail 200 --json.

Meaning: SEARXNG_HEALTHCHECK_FAILED means the endpoint did not return bounded JSON search results. SEARXNG_NOT_MANAGED means the selected service is external or disabled, so Argus cannot repair it.

Recover: For managed SearXNG only, run argus repair searxng --dry-run --json, then argus repair searxng --yes --json. For external SearXNG, repair the external service under its own controls and rerun argus doctor --json.

FxEmbed or X ingestion fails

Inspect: Always run argus doctor --json and argus logs argus --tail 200 --json. For VPS-hosted FxEmbed, also run argus logs fxembed --tail 200 --json; that service log does not exist for Cloudflare or external mode.

Meaning: FXEMBED_X_SMOKE_FAILED means FxEmbed could not pass the X source smoke check. FXEMBED_DIAGNOSTIC_SKIPPED means X had no diagnostic target, and FXEMBED_DISABLED confirms X is disabled. An X SOURCE_SMOKE_FAILED or SOURCE_SMOKE_TIMEOUT means the isolated X diagnostic did not ingest its configured target.

Recover: For VPS-hosted FxEmbed, inspect argus repair fxembed --dry-run --json, apply argus repair fxembed --yes --json, then rerun doctor. For Cloudflare or an external endpoint, repair it under that service's controls; Argus does not mutate those deployments.

Telegram or Web parsing fails

Inspect: argus doctor --json and argus logs argus --tail 200 --json.

Meaning: Telegram supports public preview channels only. A Web diagnostic can reject a private or unsafe target; public Web fetches enforce the SSRF destination policy. Source smoke failures are reported as SOURCE_SMOKE_FAILED or SOURCE_SMOKE_TIMEOUT.

Recover: Replace the public channel or URL with a supported target, then run argus config apply /opt/argus/argus.yaml --dry-run --json and argus config apply /opt/argus/argus.yaml --yes --json.

API returns 401 or 400

Inspect: argus config show /opt/argus/argus.yaml --json and argus doctor --json.

Meaning: 401 means a /v1 request lacks the configured Bearer token or it does not match. 400 is request validation, such as an invalid limit, timestamp, cursor, diagnostic body, or configuration-management request; it is not repaired by restarting the service.

Recover: For a missing or rotated API secret, run argus secrets set ARGUS_API_TOKEN --dry-run --json, then argus secrets set ARGUS_API_TOKEN --yes --json, and update the caller's Authorization: Bearer header. For a 400, correct the client request and repeat it; there is no server mutation to run.

Summary fails

Inspect: argus doctor --json and argus config show /opt/argus/argus.yaml --json.

Meaning: 409 {"error":"intelligence is disabled"} means intelligence or its API key is unavailable. A malformed summary body or a limit outside 1 through 100 returns 400. Provider failures are not converted into an Argus recovery mutation.

Recover: Correct the intelligence configuration and secret reference, then run argus config apply /opt/argus/argus.yaml --dry-run --json followed by argus config apply /opt/argus/argus.yaml --yes --json. Correct a bad request without changing the service.

Query fails or returns weak context

Inspect: argus config show /opt/argus/argus.yaml --json, then run argus query latest-news --limit=50 --json.

Meaning: A 409 means OpenRouter intelligence is disabled or unavailable. A sourced but weak answer means the bounded recent-record selection did not contain enough matching evidence; argus query is not semantic retrieval or a replacement for an agent's deliberate API traversal.

Recover: Fix intelligence configuration as for summaries. For evidence coverage, use record filters and the research skill to inspect the stored corpus and transient primitives; do not increase confidence beyond the returned data.

X replies look incomplete

Inspect: Fetch the root record and GET /v1/records/:id/conversation with the configured API token.

Meaning: Reply tracking is opt-in, ends at maxTrackingHours, observes at most 500 distinct replies per refresh while following distinct cursors, and retains at most maxPerPost in the configured order. complete describes the bounded collection run, not all replies on X.

Recover: Choose a longer Hot, Standard, Niche, or custom tracking horizon for future posts and apply the reviewed configuration. Use the authenticated transient X conversation primitive for read-only deeper traversal when needed; its response is not persisted.

Update fails

Inspect: argus status --json, argus doctor --json, and argus logs --tail 200 --json.

Meaning: UPDATE_RELEASE_UNVERIFIED, UPDATE_STATE_UNAVAILABLE, UPDATE_STATE_INCOMPATIBLE, or UPDATE_HEALTHCHECK_FAILED means Argus cannot establish a verified healthy candidate. RELEASE_MANIFEST_REQUIRED means the installed CLI lacks the signed release composition. UPDATE_INSTANCE_NOT_ONBOARDED means a newer stable release is available but no instance is onboarded on this host yet.

Recover: Preserve /opt/argus/backups, update-state.json, and release-context.json. Run argus update --dry-run --json; if it returns a reviewed plan, run argus update --yes --json. If the candidate is unhealthy and a persisted backup is available, use the rollback sequence instead.

Rollback is unavailable

Inspect: argus update --rollback --dry-run --json, then argus doctor --json.

Meaning: UPDATE_ROLLBACK_UNAVAILABLE means required rollback support or recovery material is unavailable: this CLI integration does not support rollback, no verified rollback release is selected, the signed release context or persisted update state is missing, unreadable, or invalid, or a persisted recovery path escapes the instance root. UPDATE_ROLLBACK_INCOMPATIBLE means readable persisted update state has no backup, or its recorded backup/release pairing fails the required schema, manifest, or version metadata. Rollback dry-run fetches and selects the signed rollback release only; it does not validate the persisted backup or prove the rollback can be applied. Backup availability and compatibility are checked during apply.

Recover: Do not delete recovery files. Run the dry-run first, then use argus update --rollback --yes --json only after reviewing the selected release and accepting that apply can still return an unavailable or incompatible rollback error. If it does, restore from the separately retained SQLite or PostgreSQL backup and verify with argus status --json and argus doctor --json.