> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Isolate failures in application recording, local delivery, server storage and reader access.

Check the application, local queue, relay, server and reader separately. The SDK writes
locally; the relay forwards those records. A local flush does not confirm server delivery,
and a successful HTTP connection does not establish that the application recorded anything.

## Establish a delivery-health baseline

Set the application's queue path, the server URL and a read token, then inspect delivery:

```sh theme={"system"}
export VEXLO_SPOOL_DIR=/path/to/application/spool
export VEXLO_ENDPOINT=http://127.0.0.1:8080
export VEXLO_TOKEN=your-read-token
vexlo relay status -spool-dir "$VEXLO_SPOOL_DIR"
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
curl --silent --show-error "$VEXLO_ENDPOINT/v1/health" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
curl --silent --show-error "$VEXLO_ENDPOINT/v1/coverage" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

For the relay's default health address, check:

```sh theme={"system"}
curl --silent --show-error http://127.0.0.1:9101/healthz
```

Use your configured `-health-addr` instead when it differs. The relay also exposes `/metrics`
on that listener. These local endpoints are separate from authenticated `/v1/health`.

| Check | What to inspect |
| - | - |
| `whoami` | Token role and team scope |
| `relay status` | Known writers, backlog, sent records and counted drops in this queue |
| Relay `/healthz` | Local forwarding and queue health |
| Server `/v1/health` | Storage usage, server mode and scoped service loss data |
| Server `/v1/coverage` | Observed service activity and reported losses |

A zero backlog can mean records were sent or terminally dropped. Compare sent and dropped
counters, then find a known execution on the server. Server loss information depends on what
reached the server; compare it with the local queue.

## No recording appears

1. Confirm `init()` ran before the marked entry point. A `@vexlo.step` outside a trace does
   not start a recording. Inspect `vexlo.diagnostics()` in the application process, including
   `steps_outside_trace` and internal-error counters.
2. Check local `enabled` configuration and service policy. Confirm the SDK and relay use the
   same queue directory.
3. Run `relay status` against that directory. If no writer appears, confirm the SDK selected that
   directory and the entry point executed. Inspect a backlog for delivery failures. Check relay logs
   and the destination/token settings.
4. Check server access with `whoami`, then reader team, environment, service and time filters.
   A correctly recorded trace outside your token's scope looks absent.

### The server was unreachable

Network errors, `429`, and HTTP `500`, `502`, `503` and `504` are retryable. Restore the
server or correct the destination while the records remain queued. Queue pressure can evict unsent
records during an outage. See
[local queue retention](https://docs.vexlo.ai/deployment/retention.md#local-queue-retention-and-outages).

### The server rejected records

Other response statuses are terminal, including invalid or wrong-role credentials. The relay
counts the rejected records as `daemon_terminal_reject` and advances past them. Correcting the
credential prevents later rejections; it does not automatically send the rejected records again.

A wrong-role relay credential produced this queue status:

```text theme={"system"}
spool: 5.5KiB / 2.0GiB (0.0%)

writer 1794128849-61566-b2ff3da8
  service: docs-service  instance: 476d8e192837d148514148037a3cc8c5
  state: active
  backlog: 0 records, 0B
  records sent: 7
  dropped:
    none

writer 1794128852-61643-498ca79f
  service: docs-service  instance: c7b2935936099590f11dd6eae99d7d03
  state: active
  backlog: 0 records, 0B
  records sent: 0
  dropped:
    daemon_terminal_reject: 7
```

The first writer sent seven records. The second had seven terminal drops and zero backlog.
After replacing the credential, those dropped records remained counted and were not retried.
The raw files still occupied queue space; their presence did not make the records pending.

Do not reset delivery cursors or edit queue files to attempt recovery. Correct the destination
or credential, verify delivery of a new identified execution, and preserve diagnostic files
for investigating the loss.

## Authentication or transport fails

| Symptom | Check and correction |
| - | - |
| `401 unauthenticated` | Send the right bearer credential; check whether it was revoked and whether it exists in this server database |
| `403 forbidden_role` | Use a read token for query routes and an ingest token for the relay |
| Trace ID returns `404` | Check team scope and retention; the response does not prove the request never ran |
| Non-loopback server refuses startup | Configure the TLS certificate/key pair or use loopback for the local deployment |
| Relay refuses an HTTP destination | Configure HTTPS, or explicitly acknowledge plaintext with the corresponding setting |

The API returned this response after a credential was revoked:

```json theme={"system"}
{"error":{"code":"unauthenticated","message":"token revoked"}}
```

Follow [Authentication](https://docs.vexlo.ai/deployment/authentication.md) for issuance, replacement and transport
configuration. Token commands must open the same database the server uses.

## Calls or values are missing

| Observation | Check |
| - | - |
| A helper is absent | Instrumentation, active trace context, trace lifetime, loss and step pagination |
| A call has no reported completion | `completeness`, loss data and child-work lifetime; do not infer a live hang |
| A preview exists but bytes are unavailable | Values endpoint response and server value budget; metadata is historical |
| A value remains `pending` | Its bytes are not readable now. A later read returns `stored` if they become readable; the state alone does not identify the cause or promise arrival. |
| Values are `not_captured` | Local capture settings and supported policy restrictions |
| Values are truncated | SDK capture bounds; the original object was larger than its representation |
| Lower `max_value_bytes` policy does not reduce Python capture | This accepted policy field is not currently enforced by the Python capture engine |

Review [Capture controls](https://docs.vexlo.ai/instrumentation/capture.md) before changing what leaves the process.
For missing bytes, [Retention](https://docs.vexlo.ai/deployment/retention.md) distinguishes capture decisions, delivery
loss and server expiry. Increasing a budget cannot reconstruct bytes already unavailable.

### Capture resumes after a policy outage

The Python SDK falls back to `init()` configuration when its policy file is unusable or
older than 300 seconds. A remote restriction is therefore temporary while policy delivery is
unavailable. Put required restrictions in local configuration, then use policy only to lower
that ceiling. See [policy freshness](https://docs.vexlo.ai/deployment/configuration.md#policy-freshness-and-fallback).

## A recording remains open or incomplete

Read `completeness` separately from the root call's status. An `in_flight` attempt has an
entry record without a completion record; a lost completion leaves the same evidence as a
still-running function.

Follow every step page, collecting distinct paths until `next_cursor` is `null`. Compare
that count with the newest `step_count` and restart the walk if they differ. A walk while
records are still arriving does not establish exhaustive coverage. Slowest-first order puts
calls without a completed duration last, beyond the first page when the trace is large.

See [HTTP traces and values](https://docs.vexlo.ai/reference/http-traces.md) for exact fields and pagination semantics.

## Capacity check or relay health fails

A nonzero `vexlo check` indicates invalid configuration, including a value budget greater
than the total capacity of its volume. `serve` applies the same capacity validation. Reduce
the budget or select a larger volume before using `-allow-overcommit`. Values expiring before
call records are reported without failing the check.

With a backlog, relay health is degraded until the first accepted send, or after five minutes
without an accepted send. Queue usage above 80% of its budget also degrades health. Inspect
`relay status` and relay logs to distinguish destination failure, terminal drops and pressure
eviction.

## An agent cannot connect or read data

The MCP server requires `VEXLO_API_URL` and a read-role `VEXLO_TOKEN`. Set `VEXLO_API_URL` to
the same server base URL used for `VEXLO_ENDPOINT`, without `/v1`. It checks the server's
capabilities and API version, then the credential's identity and role. A successful connection
with no results still requires checking service, team, environment and instrumentation.

Use [Connect an agent](https://docs.vexlo.ai/agents/connect.md) for the supported host setup and
[MCP tools](https://docs.vexlo.ai/reference/mcp.md) for exact filters and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.