No ... sources were detected... or exit code 2 | Xerg could not find any supported local runtime data, or any pulled OpenClaw data. | Run npx @xerg/cli@latest doctor, then pass --runtime, --log-file, and --sessions-dir as needed, or inspect SSH or Railway sources directly for OpenClaw. |
No Claude Code sources were detected under ... | No *.jsonl session transcripts exist under the checked projects directory. | Run a Claude Code session first, or point Xerg at the right location with --claude-code-dir <path>. Confirm with npx @xerg/cli@latest doctor --runtime claude-code. |
| Cursor CSV audit runs but shows no retry or loop findings | Usage CSV rows carry no runtime structure, so structural findings are impossible from that source. | This is expected. Cursor audits surface Cursor-specific findings only. If your framework can export per-event data, use npx @xerg/cli@latest ingest --file payload.json instead. |
xerg ingest rejects the payload with per-event errors | The event payload has invalid fields — bad timestamps, unknown event types, duplicate IDs, or negative/fractional numeric values. | Fix the listed events. Token and count fields must be nonnegative integers; costUsd and latencyMs must be nonnegative numbers. See ingest for the format. |
| OpenClaw or Hermes collector says the port is occupied | Another process already owns the loopback port. | Re-run the selected collector with --port 4320 and use its printed endpoint in the runtime plugin. |
| OpenClaw collector receives metrics or logs | OpenClaw diagnostics exporters were enabled beyond the supported trace rail. | Set traces: true, metrics: false, and logs: false; Xerg accepts only OTLP/HTTP protobuf traces. See OpenClaw trace collection. |
| Hermes trace capture cannot reconcile economics | The capture has no matching local correlation key, no auditable state.db, an unsupported plugin build, or conflicting observer/trace totals. | Keep the capture on the installation that created it, pass --runtime hermes --state-db <file>, use the exact certified commit, and inspect the emitted diagnostics. Xerg deliberately retains the state aggregate on conflict. |
| QM doctor says export contract v1 is not installed or drifted | The reviewed views are absent, their fingerprint/columns/types changed, or QM changed under them. | Have the database owner review and apply xerg connect qm --print-sql. Xerg never falls back to base tables or guesses renamed columns. |
| QM doctor reports unsafe privileges | The supplied role can read base tables, write, own/create, inherit another role, or bypass RLS. | Revoke the extra privileges and use the dedicated xerg_reader contract role. Do not use QM’s general DATABASE_URL. |
| Fly QM doctor shows privilege warnings | Contained mode uses QM core’s existing database authority and does not claim database-level least privilege. | Confirm the report says contained-operator, process, and databaseLeastPrivilege: false. Use strict direct mode if your database supports a truly isolated role. |
| QM says the identity-key fingerprint changed | XERG_QM_IDENTITY_KEY was lost, replaced, or set for a different deployment. | Restore the backed-up deployment key. Rotate only as an explicit identity-boundary change; historical comparison continuity cannot cross it. |
| QM shows tokens but cost unavailable | QM recorded openrouter/auto, a zero/negative placeholder, or an explicit model without observed/catalog cost. | Treat spend thresholds as unevaluable (exit 5). Use an approved explicit deterministic model for a priceable canary; never guess the routed model or call the usage free. |
| QM tool history is shorter than the audit window | QM prunes run_activity after one hour. | This is expected under the current one-shot boundary. Durable model/run economics remain auditable; older tool activity is unavailable and no monetary tool-loop claim is made. |
| Fly QM export fails | The local Fly CLI is unauthenticated, the app is wrong, the CLI versions differ, or the pinned exporter, views, identity key, or XERG_QM_TRUSTED_EXPORT=1 is absent in core. | Run fly auth whoami, then xerg doctor --runtime qm --fly-app <core-app>. Keep Fly and database credentials out of Slack sandboxes. |
Could not determine whether the provided local files belong to OpenClaw or Hermes | The explicit local paths look plausible for more than one supported runtime. | Re-run with --runtime openclaw or --runtime hermes so Xerg knows which parser to use. |
The --compare flag needs local snapshot history... | You used --compare with --no-db. | Remove --no-db or use --db <path> so Xerg has a local snapshot store. |
--details conflicts with another output mode | Detailed output is a human report, while JSON, Markdown, print-example, and dry-run payloads are separate projections. | Choose exactly one output mode. For automation, keep --json; for exhaustive terminal reading, use --details. |
| Human output stacks labels or leaves one long line | Xerg packs complete key: value fields when they fit, stacks fields below 64 columns, and keeps copyable commands, paths, URLs, identifiers, money, SQL, JSON, and TOML intact. | Widen the terminal for denser layouts. Copy the complete command line beneath its label; an indivisible token may soft-wrap visually in the terminal without gaining a logical line break. |
| Human report spacing differs from an earlier release | Xerg separates multi-line finding, signal, and repeated-chain records while keeping short ranked lists compact. Human terminal layout may change between releases; JSON is the stable automation interface. | Read terminal output as a human report. Use --json for scripts and other byte-sensitive automation. |
| Expected color is absent | Color is supplementary and disabled for unsupported/non-TTY streams, NO_COLOR, NODE_DISABLE_COLORS, TERM=dumb, and normal CI output. | Remove the disabling environment setting or use a color-capable interactive terminal. Never depend on ANSI color to interpret a status. |
No prior comparable audit was found... in notes | Xerg completed, but no compatible baseline exists yet. | Re-run the same audit after your next change. |
| Install fails with an unsupported engine warning | The active Node version is outside Xerg’s supported range. | Use Node 22.13.0 or newer, then retry the command. |
| SSH audit cannot connect or pull files | SSH access, key access, or rsync is missing. | Verify ssh connectivity, remote key access, and that rsync is installed locally and remotely. |
| Railway audit says it cannot reach the service | The railway CLI is missing or unauthenticated, the current directory is not linked to a reachable Railway service, the current directory is linked to the wrong service, or the explicit Railway IDs do not point at the OpenClaw app. | Run railway login, then either run railway link in the directory where you invoke Xerg and choose the OpenClaw app service, or pass explicit --project, --environment, and --service values. Re-run npx @xerg/cli@latest doctor --railway to confirm the target. |
| Railway audit reaches a service but still reports no OpenClaw data | The linked or selected Railway service is probably not the OpenClaw app, or the app stores logs and sessions outside the default paths. | Re-link or re-select the OpenClaw app service. If the app writes elsewhere, pass --remote-log-file and --remote-sessions-dir. |
Push says No API key configured | Xerg could not find a paired or CI credential. | Run npx @xerg/cli@latest activate --push-latest. In CI, set XERG_API_KEY through the CI provider’s secret manager. |
xerg activate keeps waiting | The browser has not approved the short-lived code, workspace creation is still finishing, or the pairing expired. | Return to the exact approval URL printed by the CLI, confirm the named workspace, and approve it before the ten-minute expiry. The code survives SignUp, SignIn, and automatic workspace creation. |
| Browser approval says the CLI requested another organization | The active Clerk workspace does not match --organization-id. | Use the organization switcher on the approval page. The code remains in the URL, and approval stays disabled until the full organization ID matches. |
| Stored credential is bound to another API environment | A paired staging/production credential conflicts with XERG_API_URL. | Unset the conflicting variable, or intentionally re-pair with activate --replace --organization-id org_... against the intended API. Xerg never silently sends a bound credential to another environment. |
| Browser activation reports that rotation is required | The workspace’s active API key predates recoverable encrypted storage. | Rotate the key once in Dashboard Settings, then rerun npx @xerg/cli@latest activate --replace. |
| A Codex user expects “Codex” in the audit-source list | Codex is the agent host executing setup, not a native Xerg data source. | Run npx @xerg/cli@latest doctor, then audit the OpenClaw, Hermes, Claude Code, Cursor export, or ingest source it finds. |
Push reports monthly_snapshot_limit_reached | The Free workspace has stored 100 distinct snapshots this UTC month. | Wait for the printed UTC reset or choose a paid MAAS band. Repeating an identical push remains safe because deduplicated retries do not consume quota. |
xerg focus ... is an unknown command | Xerg 0.18.0 retired provider-generated FOCUS ingestion, and 0.21.0 removed the temporary compatibility tombstone. | Keep your source files; Xerg never deletes them. Use Xerg for agent-runtime audits, and see the FOCUS retirement note for the product boundary. |
xerg push says no cached audit snapshots found | There is no audit in the default local snapshot store. | Run npx @xerg/cli@latest audit first, or use npx @xerg/cli@latest push --file <path>. |