Troubleshoot agent setup

Start with the symptom. Each fix keeps credentials out of chat: enter them only in a browser, a private file or your client’s own settings.

Quick checks

npx --yes metergraph-cli@latest doctor
npx --yes metergraph-cli@latest status

doctor sends no credentials. On a healthy, supported service it exits with code 3, authentication_required. That is its best result: the service is reachable, and no workspace is connected yet. Pass --url with your installation’s origin for a deployment other than hosted cloud.

status checks this project’s saved sign-in against the service. In an MCP client, ask the agent to call metergraph_get_workspace_context and metergraph_get_capabilities.

Add --json to any CLI command to get one line of JSON. outcome names the exit code, and error.reason is a fixed token, such as access_revoked, that says why.

CLI exit codes

Code	Outcome	Common reasons	What to do
0	ok		Done. After skill install, restart the client and check that it lists the skill.
1	internal_error		Rerun with --json and report the command, exit code and reason. Do not include tokens.
2	invalid_input	invalid_url, non_hosted_workspace_required, non_hosted_origin_required, an unknown option	Fix the command. --url takes a bare origin: https:// on any host, or http:// only for localhost, 127.0.0.1 and [::1]. A deployment other than hosted cloud needs --url and --workspace. No request was made.
3	authentication_required	bearer_token_required	From doctor, this means the service is healthy. Run setup or login to connect a workspace.
4	connection_failed	timeout	Check the origin and network. For a customer-local bundle, check that it is running and use the address reachable from this computer. Raise --timeout-ms on a slow network.
5	unhealthy	reported_unhealthy, server_error	The service is up but unhealthy. Retry later, or for your own installation check its logs.
6	unsupported	runtime_not_supported, run_on_local_machine, client_not_supported, no_browser_requires_terminal, prerequisite_unknown, oss_ingest_operator_handoff, unrecognized_profile, content_access_unsupported, exceeds_service_bounds, signup_hosted_only	Sign-in cannot run in this environment or with these options. Run login or setup on your own computer, not in CI, SSH or a cloud workspace. A non-hosted setup needs --confirm-prerequisites. On the open-source server, oss_ingest_operator_handoff is the expected end of setup: the operator configures ingest. Claude Desktop and ChatGPT cannot load project skills; use Connect a coding agent. The CLI never reads content or runs replays. Reduce --days or --limit to the service’s bounds. Nothing was written.
7	redirect_rejected	redirect	The address redirects. Use the final origin directly.
8	conflict	bound_to_other_workspace, bound_to_other_origin, not_owned, modified, update_required, env_tracked, locked	The project is bound to another workspace or origin: rerun with --reconnect if you mean to switch. setup never moves an existing ingest key to another workspace, even with --reconnect; restore the original workspace to reuse it. A skill file you or another tool edited is never overwritten: restore or remove it, or run skill update for an older revision this CLI installed. Untrack the env file or choose another with --env-file. A skill lock left by a killed command, .metergraph/skill-installations.lock, can be deleted once no other metergraph command is running. Nothing was changed.
9	filesystem_error		Check that the project and config directories exist and are writable by you. On Linux and macOS the config directory must be 0700 and owned by you.
10	authorization_failed	access_denied, timeout, cancelled, callback_invalid	Browser sign-in or approval did not finish. Rerun and complete it in the browser on the same computer. A browser signed in to another workspace must switch workspace in Metergraph first. Nothing was saved.
11	verification_failed	workspace_mismatch, profile_mismatch, scope_mismatch, trace_not_found_within_bounds, verification_timeout	The service’s answer did not match what was expected. For workspace_mismatch, choose the workspace you passed with --workspace. For verify, see incomplete evidence.
12	login_required	not_signed_in, access_revoked	The project has no usable sign-in: none was saved, it expired, an owner revoked it, or you lost workspace access. Run metergraph login --runtime local again.
13	revocation_unconfirmed		logout removed the local sign-in, but the service did not confirm revocation. An owner can revoke the connection on the Keys page.
14	capability_unavailable		This deployment does not offer the read to a Metadata sign-in. See unavailable capabilities. No data was read.
15	permission_denied	insufficient_scope, forbidden	The service refused the read for this sign-in. Check your workspace membership.
16	rate_limited	rate_limited	Wait for retry_after_seconds, when given, then retry. Nothing was retried automatically.
17	cancelled	cancelled	The command was interrupted. Read commands change nothing, so rerun it.

Codes 10 to 17 and the sign-in, setup and read commands need metergraph-cli 0.2.0 or later. If metergraph login is an unknown command, an older copy is installed; use npx --yes metergraph-cli@latest.

Failed authorization

The CLI. See codes 6, 10 and 11 above. setup needs an owner or member of the verified workspace to approve the ingest key in the browser. If that approval never reached the CLI, rerun the same command. It asks for a new approval for the same setup, and the service replaces that setup’s pending key rather than issuing a second one.

An MCP client. Browser sign-in opens Metergraph in your default browser. If the client reports invalid_scope, the service does not yet name the role to request; use a coding-agent key. If the browser is signed in to another workspace, switch workspace there and sign in again from the client: /mcp in Claude Code, codex mcp login metergraph in Codex, or the server’s sign-in prompt in Cursor. A client running in the cloud or over SSH cannot complete a loopback sign-in on your computer; use a coding-agent key there.

A keyed connection that answers 401 usually has no token: the client was started from a shell or launcher that did not set METERGRAPH_AGENT_TOKEN. Check only that the variable is set, never its value, then restart the client. A key from a different deployment or workspace also fails: hosted keys do not work on customer-local or customer-owned AWS installations.

Revoked or stale credentials

• An owner revoked the connection on the Keys page, or you lost membership of the workspace. The CLI exits 12 with access_revoked; an MCP client gets 401. Sign in again, or ask an owner for a new key.
• An owner changed a key’s role. Metergraph replaced the key, so the saved one no longer works. Save the new key in the client’s environment and restart the client.
• The CLI refreshes an expiring sign-in once. If a refresh was interrupted, it never resends the old refresh token and asks you to run login again.
• A setup ingest key that no longer verifies, or whose .env was lost, needs metergraph setup ... --repair, which asks a workspace member to approve a replacement for that exact key.

Unavailable capabilities

Capabilities depend on the deployment and the credential’s role, not on your plan. Call metergraph capabilities or metergraph_get_capabilities to see what is available and which scope each needs.

• A content or replay tool fails on a browser sign-in. Browser sign-in is Metadata. Use a coding-agent key with the Debug or Replay role. The CLI never reads content or replays, whatever the role.
• A tool is unavailable on this deployment. Some editions do not offer trace content, replay or reports. See deployment capabilities.
• An MCP tool returns forbidden when the key’s role lacks the scope the tool needs, unsupported_capability when the deployment does not offer it, and replay_not_eligible when a trace cannot be replayed safely.
• A response carries the capability_unavailable warning. Part of the answer needed a capability you do not have, so it was left out. The rest is still valid.

Incomplete evidence

A successful answer can still be partial. Read its completeness fields before drawing a conclusion.

• complete: false or a truncated warning. The answer hit a row, time or size limit. Totals cover the returned rows only, not the workspace. Narrow the window or route, or page with --cursor.
• spans_limited, content_omitted or evidence_omitted warnings. A trace had more spans than one response returns, retained content was absent or not readable with this role, or report evidence was left out.
• empty: true. Nothing matched in the window. This is a successful result, not proof that no traffic exists elsewhere.
• metergraph verify exits 11 with verification_timeout. The service answered, but the exact trace was not visible before the deadline. Processing can lag ingestion. Rerun with a longer --timeout-ms. Exit 4 with that reason means no valid answer arrived at all.
• trace_not_found_within_bounds. verify used all its polls (--max-attempts) without finding a processed trace with that exact ID or request ID in the --since to --until window. Check that the application used the ingest key from this workspace and that the window covers the invocation, then rerun with a higher --max-attempts or --timeout-ms.
• application_traffic_verified is false. It always is in the CLI’s results. A matching trace proves it reached the workspace, not that your application sent it. Tests, mocks and demo data are not real traffic.