Troubleshooting

Start here when an agent is configured but its data isn’t showing up in Scout Trails, shows up in the wrong place, or is missing detail. Agents report export failures only in their own logs, never in the conversation, so the first step is usually to read that log.

Read the agent’s export errors

Claude Code: start a session with a debug log, use a tool, then search the log for [3P telemetry], which marks errors from the exporters you configured:

claude --debug-file /tmp/claude-debug.log
grep '3P telemetry' /tmp/claude-debug.log

Codex CLI: start Codex with verbose logging written to a directory you choose, use a tool, then read the log file in that directory:

RUST_LOG=debug codex -c log_dir=./codex-log

The errors carry a gRPC status and a message from Scout Trails. Look them up in the table below.

Error statuses

Status and message	Cause	Fix
`PERMISSION_DENIED`: `missing authorization header`	The agent sent no `Authorization` header.	Check that the header setting is present and spelled correctly: `OTEL_EXPORTER_OTLP_HEADERS` for Claude Code, `headers` under `[otel.exporter.otlp-grpc]` for Codex.
`PERMISSION_DENIED`: `authorization header must use Bearer scheme`	The header value doesn’t start with `Bearer` exactly.	Use `Authorization=Bearer <key>` (Claude Code) or `"Authorization" = "Bearer <key>"` (Codex), with a capital B and one space.
`PERMISSION_DENIED`: `authorization Bearer value is empty`	Nothing follows `Bearer` . In a shell, this usually means the value wasn’t quoted.	Quote the whole value: `export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <key>"`.
`PERMISSION_DENIED`: `unknown ingest key`	The key doesn’t match any active key. It was mistyped, rotated, or revoked, its actor was deactivated, or it isn’t an ingest key at all (API keys, which start with `wb_api_`, don’t work here).	Copy the current key from the Actors & ingest keys tab and update the agent. See Ingest keys.
`RESOURCE_EXHAUSTED`: `monthly event limit reached ...`	Your organization has used its monthly event allowance.	Contact Scout support to raise the allowance; organization admins can’t change it from the dashboard. See Usage limit.
`UNAVAILABLE`: `keystore unavailable`	Scout Trails couldn’t check the key at that moment.	None needed. The agent retries the batch.
`UNIMPLEMENTED`	The agent is sending a signal the endpoint doesn’t accept, usually metrics.	Turn off the metrics exporter for Scout Trails: leave `OTEL_METRICS_EXPORTER` unset or set to `none` (Claude Code), or don’t point `metrics_exporter` at the endpoint (Codex).

A rejected batch is discarded, not queued. Data sent while the key was wrong doesn’t appear after you fix it.

Nothing shows up in the dashboard

Work through these in order.

Look at the right slice of the dashboard. On Tool calls, set Window to 1h, Scope to Whole organization and every other filter to Any, then select Apply.
Check you are in the right organization. The key decides which organization receives the data. If you belong to several, open the organization menu in the header and switch. See Data lands in the wrong organization.
Make the agent use a tool. Sessions are built from tool calls. A conversation in which the agent answers without running any tool doesn’t create a session.
Restart the agent. Both agents read their telemetry configuration only at startup, so a session that was already running when you changed it keeps the old settings.
Wait a few seconds. Agents send events in batches; Claude Code sends every 5 seconds by default.
Check the configuration is being read.
- Claude Code: the variables must be in ~/.claude/settings.json, your shell, or managed settings. Claude Code ignores them in a project’s .claude/settings.json and .claude/settings.local.json. A value in a settings file overrides the same variable in your shell, so an old key left in ~/.claude/settings.json wins over a new one you exported. A project can also turn telemetry off with OTEL_LOGS_EXPORTER set to none.
- Codex: the [otel] block must be in ~/.codex/config.toml, and the exporter must be the nested [otel.exporter.otlp-grpc] table. A project’s .codex/config.toml is read only for trusted projects.
Check the protocol. The endpoint accepts gRPC only. Claude Code needs OTEL_EXPORTER_OTLP_PROTOCOL=grpc, and Codex needs the otlp-grpc exporter. http/protobuf, http/json and otlp-http don’t work.
Check the network. From the machine running the agent, confirm the endpoint is reachable and negotiates HTTP/2:
```
openssl s_client -connect ingest.scoutmonitoring.io:443 -alpn h2 </dev/null 2>/dev/null | grep -i alpn
```
The output should include ALPN protocol: h2. If the connection fails or times out, a firewall or proxy is blocking it; see Network requirements.
Read the agent’s export errors as described in Read the agent’s export errors.

Data lands in the wrong organization

Telemetry always goes to the organization that owns the actor whose key the agent sends. If your sessions appear in a different organization than you expect, the key was copied from that organization’s Actors & ingest keys tab.

Switch to the organization the data should go to, using the organization menu in the header.
On its Actors & ingest keys tab, create an actor for the machine, or copy the key of the existing one.
Replace the key in the agent configuration and restart the agent.

Data that already arrived stays in the organization that received it.

Sessions appear under the wrong actor

Every event is attributed to the actor whose key sent it. If several machines share one key, all their sessions show that actor’s display name. Give each machine its own actor and key. See Actors.

Tool calls have no arguments

Claude Code: the Arguments card reads No arguments recorded. when OTEL_LOG_TOOL_DETAILS=1 isn’t set. Set it in ~/.claude/settings.json, your shell, or managed settings, not in a project’s settings, then restart Claude Code. Without it, MCP calls also show the tool name mcp_tool.
Arguments are cut short: Claude Code shortens individual values over 512 characters and caps the whole input at about 4 KB. This happens before the data leaves the machine.
Tools that take no input have no arguments to record.

Tool calls have no result

Claude Code doesn’t include tool output on the events Scout Trails uses, so the Result card of every Claude Code tool call reads No result recorded. Codex tool calls include their output. See What Scout Trails collects.

Codex sessions show no cost

Codex doesn’t report model cost on its events, so the Cost column reads — for Codex sessions. Claude Code sessions show cost.

Declined Codex tool calls don’t appear as denied

Only Claude Code’s permission decisions appear as tool calls with status denied. A tool call you decline in Codex isn’t shown.