Verify & Troubleshoot

​

Verification Checklist

​

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

ls -la .sec0/audit-*.ndjson

head -1 .sec0/audit-2026-02-06.ndjson | jq .

​

Common Errors

​

[sec0] Config file not found

ls -la sec0.config.yaml

​

[sec0] localDir is required

controlPlane:
  sec0Dir: /var/sec0-data

​

[sec0] localSignerPath is required

1. Generate a key:

mkdir -p .sec0/keys
openssl rand -base64 32 > .sec0/keys/ed25519.key

2. Set the key path in config:

controlPlane:
  localSignerPath: ./.sec0/keys/ed25519.key

​

[sec0] Signing key file not found

ls -la ./.sec0/keys/ed25519.key
# Should be readable by the Node.js process

​

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

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

​

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

​

Debug Tips

​

Enable Debug Logging

sec0SecurityMiddleware({
  // ...
  runtime: {
    debug: {
      policySync: true,
      sast: true,
      dast: true,
    },
  },
})(server);

​

Inspect Audit Envelopes

# 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

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);

• Instrumentation Config
• Middleware Options
• Gateway Config
• Policy Schema