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

# Verify & Troubleshoot

> Confirm Sec0 is running correctly and resolve common issues.

## Verification Checklist

After integrating Sec0, confirm each layer is working:

### Instrumentation

* [ ] `initializeSec0App()` or `loadStandardConfig()` completes without errors
* [ ] Decorated methods execute and return results normally
* [ ] Audit files appear in the configured `appenderDir`

### Middleware

* [ ] `sec0SecurityMiddleware(options)(server)` wraps without errors
* [ ] Tool calls succeed and audit envelopes are written to `sec0.dir`
* [ ] Registry freeze is active (registering new tools after wrapping throws)

### Gateway

* [ ] `startGatewayServer()` binds to the configured port
* [ ] `POST /mcp/:server/:tool@version` returns valid responses
* [ ] Response headers include `x-trace-id` and `x-span-id`
* [ ] Audit envelopes are written for each gateway call

### Adaptive Approvals

* [ ] Policy includes `security.side_effects.human_escalation` for the intended scope
* [ ] Policy includes `security.side_effects.approve_high_risk: true`
* [ ] `enforcement.escalate_on` is set (or omitted so it falls back to `enforcement.deny_on`)
* [ ] Denied responses include `escalation_id` and `escalation_status` when escalation is created
* [ ] Audit envelopes include `escalation_id` for escalated denials

### Audit Output

Check your configured audit directory for daily-rotated files:

```bash theme={null}
ls -la .sec0/audit-*.ndjson
```

Each line is a valid JSON envelope:

```bash theme={null}
head -1 .sec0/audit-2026-02-06.ndjson | jq .
```

## Common Errors

### `[sec0] Config file not found`

**Cause:** `sec0.config.yaml` is missing or the path is incorrect.

**Fix:** Ensure the file exists and the path is correct:

```bash theme={null}
ls -la sec0.config.yaml
```

### `[sec0] localDir is required`

**Cause:** Missing `localDir` in configuration or `controlPlane.sec0Dir` in standard config.

**Fix:** Add an absolute path:

```yaml theme={null}
controlPlane:
  sec0Dir: /var/sec0-data
```

### `[sec0] localSignerPath is required`

**Cause:** Missing or invalid signing key path.

**Fix:**

1. Generate a key:

```bash theme={null}
mkdir -p .sec0/keys
openssl rand -base64 32 > .sec0/keys/ed25519.key
```

2. Set the key path in config:

```yaml theme={null}
controlPlane:
  localSignerPath: ./.sec0/keys/ed25519.key
```

### `[sec0] Signing key file not found`

**Cause:** The key file doesn't exist at the configured path.

**Fix:** Verify the file exists and has proper permissions:

```bash theme={null}
ls -la ./.sec0/keys/ed25519.key
# Should be readable by the Node.js process
```

### `[sec0] No hop configuration found for "ClassName.method"`

**Cause:** The decorator can't find a matching entry in `app.hops`.

**Fix:** Add the hop entry to `sec0.config.yaml`:

```yaml theme={null}
app:
  hops:
    ClassName.method:
      type: agent
      nodeId: my-agent
      agentName: my-agent
      agentVersion: "1.0.0"
```

### `[sec0] app.environment must be dev, staging, or prod`

**Cause:** Invalid environment value.

**Fix:** Set `app.environment` to one of `dev`, `staging`, or `prod`.

### Control Plane Errors

* **`API key validation failed`**: Verify your `SEC0_API_KEY` is valid and the control plane is reachable
* **`controlPlaneUrl could not be resolved`**: Set `SEC0_CONTROL_PLANE_URL` environment variable or configure `controlPlane.apiBaseUrl`
* **Policy fetch fails**: Ensure `auth.apiKey` or `auth.bearerToken` is set when using control-plane policy source

### Gateway Errors

* **`audit.append must be a function`**: Pass a valid `Sec0Appender` instance
* **`quotas adapter required`**: Use `InMemoryAdapter` for development
* **Missing `x-idempotency-key`**: The gateway requires this header on all requests

### Approvals Errors

* **`no_approvers_configured`**: Human review is required, but no reviewer group resolved for this request.
* **Frequent timeout decisions**: Increase reviewer coverage or adjust strategy/quorum values in `human_escalation`.
* **Unexpected approvals/rejections**: Re-check `required_roles`, `veto_roles`, and `timeout_action` in policy.
* **Missing `escalation_id` on denied responses**: Verify `approve_high_risk` is enabled and the denial reason is included in `enforcement.escalate_on` (or `enforcement.deny_on` when `escalate_on` is not set).

### Middleware Errors

* **`REGISTRY_FROZEN`**: Cannot register new tools after wrapping. Register all tools before calling `sec0SecurityMiddleware(options)(server)`
* **`HANDLER_SWAP`**: A tool handler was reassigned after wrapping. This is blocked for integrity
* **`Cannot read properties of undefined (reading 'serviceName')`**: `otel` config is missing. Include `otel.endpoint`, `otel.serviceName`, and `otel.environment` in middleware options.

## Environment Variables

| Variable                     | Purpose                                                                 |
| ---------------------------- | ----------------------------------------------------------------------- |
| `SEC0_API_KEY`               | API key for control plane authentication                                |
| `SEC0_CONTROL_PLANE_URL`     | Override control plane base URL                                         |
| `SEC0_ESCALATION_TIMEOUT_MS` | Timeout (ms) for escalation create calls                                |
| `SEC0_SIGNER_KEY_DIRS`       | Comma-separated allowed key directories for `LocalDevSigner.fromKeyRef` |
| `SVC_TOKEN`                  | Service token for gateway auth                                          |

## Debug Tips

### Enable Debug Logging

```typescript theme={null}
sec0SecurityMiddleware({
  // ...
  runtime: {
    debug: {
      policySync: true,
      sast: true,
      dast: true,
    },
  },
})(server);
```

### Inspect Audit Envelopes

```bash theme={null}
# View latest entries
tail -5 .sec0/audit-$(date +%Y-%m-%d).ndjson | jq .

# Check for deny decisions
grep '"deny"' .sec0/audit-*.ndjson | jq .

# Count findings
grep 'agent_guard_findings' .sec0/audit-*.ndjson | wc -l
```

### Verify Signing

```typescript theme={null}
import { LocalDevSigner, canonicalize, fromBase64 } from "sec0-sdk/signer";

const signer = LocalDevSigner.fromKeyRef("file://./.sec0/keys/ed25519.key");
const envelope = { /* your envelope without the sig field */ };
const msg = Buffer.from(canonicalize(envelope));
const ok = signer.verify(msg, fromBase64(envelopeSig));
console.log("Signature valid:", ok);
```

If issues persist, cross-check your configuration against the reference pages:

* [Instrumentation Config](/docs/reference/instrumentation-config)
* [Middleware Options](/docs/reference/middleware-options)
* [Gateway Config](/docs/reference/gateway-config)
* [Policy Schema](/docs/reference/policy-schema)