> ## Documentation Index > Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Solve the most common Xerg install, audit, compare, remote, and push issues. Examples use `npx @xerg/cli@latest`. If you installed the CLI globally, substitute `xerg`. For dashboard, API, hosted MCP, Slack, website, or documentation availability, check the [Xerg status page](https://status.xerg.ai) before debugging local configuration. ## Common problems | Symptom | What it means | What to do | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 `. 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](/docs/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](/docs/openclaw-traces). | | 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 `, 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 ` 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 `. | ## Debug in the right order 1. Run `npx @xerg/cli@latest doctor`. 2. Run the plain audit without extra flags. 3. Add `--compare`, `--json`, or `--push` once the base audit works. 4. If the data is remote, validate SSH or Railway access separately before debugging Xerg flags. ## Get help * Service status: [status.xerg.ai](https://status.xerg.ai) * Pricing and plans: [xerg.ai/pricing](https://xerg.ai/pricing) * Support: `query@xerg.ai`