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. |
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. |
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 credentials. | Set XERG_API_KEY, add apiKey to ~/.xerg/config.json, or run npx @xerg/cli@latest login. |
| The signup wizard keeps waiting for the CLI | The workspace has not observed successful key verification, the wrong workspace key was pasted, or this machine already stores credentials for another workspace. | Run npx @xerg/cli@latest login --replace, paste the key from the same workspace, and use the wizard’s retry control after 60 seconds. The login prompt masks pasted characters and preserves the old credential if verification fails. |
| 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 upgrade to Pro. Repeating an identical push remains safe because deduplicated retries do not consume quota. |
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>. |