Troubleshooting

Solutions to common issues and frequently asked questions about OpsTrails.

Events Not Appearing

• Check your API key scope — Event ingestion requires a READ_WRITE scoped API key. A READ_ONLY key will return a 403 FORBIDDEN error. Check your key scope on the API Keys page in the console.
• Check the API response — The POST endpoint returns a JSON response with a success field. If success: false, the error field describes the issue (e.g. missing timezone, invalid field values). See the API Reference for error codes.
• Verify the API URL — Ensure you are posting to https://api.opstrails.dev/api/v1/events. A common mistake is to use the console URL or MCP URL instead.
• Check time format — Bare datetimes without timezone (e.g. 2025-01-15T14:30:00) are rejected. Use "NOW" or include a timezone offset.

MCP Connection Failing

• Verify the server URL — The MCP server URL is https://api.opstrails.dev/api/mcp/mcp. The double /mcp at the end is correct — the first is the API path prefix, the second is the MCP protocol endpoint.
• Check API key type — MCP requires a READ_ONLY (or READ_WRITE) scoped API key. If using Claude.ai with OAuth, the key is created automatically. For other clients, generate a READ_ONLY key in the console.
• OAuth flow issues (Claude.ai) — If the OAuth flow fails, try clearing your browser cache for Claude.ai, or remove and re-add the integration. See the Claude.ai setup guide for detailed steps.
• Bearer token format — For non-OAuth clients, pass the API key as Authorization: Bearer YOUR_API_KEY in the headers. The key must start with ot_.

Impact Analysis Shows No Metrics

• Analytics provider not connected — Impact analysis requires at least one analytics provider. Go to Settings → Analytics Integrations in the console to connect a provider. See Connecting Providers.
• Subject mismatch — Metrics are matched to events by subject (environment). If your event has subject: production but your metrics are mapped to a different subject, no match will be found. Check the subject mapping in your analytics integration settings.
• Metrics not yet collected — After connecting a new provider, it may take a few minutes for the first metrics to appear. OpsTrails fetches metrics periodically.

CLI Errors

• Authentication error — Ensure OPSTRAILS_API_KEY is set in your environment. The key must have READ_WRITE scope. See the CLI documentation.
• Network error — Check that you can reach https://api.opstrails.dev from your machine or CI/CD runner. Corporate firewalls may block outbound HTTPS requests.
• Version issues — Run npm update -g @opstrails/cli to ensure you have the latest version.

FAQ

Is OpsTrails a logging tool?

No. OpsTrails records discrete events like deployments, rollbacks, and data loads — not continuous log streams. Think of it as a structured changelog for your infrastructure, not a replacement for tools like Datadog, Splunk, or ELK.

Can AI modify my events?

No. MCP access is strictly read-only. AI assistants can query events and metrics but cannot create, modify, or delete events. Event creation requires a separate READ_WRITE API key through the HTTP API, SDK, or CLI.

What's the event payload size limit?

The total event payload (including all fields) must not exceed 10 KB. The data.description field is limited to 1,000 characters. See Limits & Quotas for full details.

Can I self-host OpsTrails?

OpsTrails is currently a managed SaaS service only. Self-hosting is not available at this time.

Which AI assistants are supported?

Any MCP-compatible AI assistant can connect to OpsTrails. This includes Claude.ai, Claude Desktop, Claude Code, VS Code with Copilot, Cursor, and GitHub Copilot CLI. See the MCP Overview for setup guides.