Cloud Troubleshooting

This page covers issues specific to dbtrail Cloud — the managed control plane, dashboard, and API. For binlog stream capture and ProxySQL time-travel issues, which apply to self-hosted dbtrail and Cloud alike, see Troubleshooting.

Server registration

"Server limit reached"

Your plan's server limit has been reached. Upgrade your plan from Dashboard → Settings → Billing to register more servers.

Server stuck in "pending" status

The server is waiting for EC2 assignment. This usually resolves within a few minutes. If it persists:

1. Check the server's connection details are correct
2. Verify the MySQL host is reachable from the dbtrail VPC
3. Contact support if the status doesn't change after 10 minutes

SSH tunnel Connection Failed

For SSH tunnel servers, if the jumphost firewall is not configured to allow dbtrail's outbound IP, the connection will fail and a Connection Failed modal will appear:

1. Note the outbound IP shown in the modal (currently 44.237.184.31)
2. Add an inbound rule to your jumphost's security group: allow TCP port 22 from that IP
3. Click Retry in the modal to resume onboarding

Server shows "error" status

An unrecoverable error occurred during provisioning. Common causes:

• MySQL host is unreachable
• Invalid MySQL credentials
• MySQL user lacks required privileges (REPLICATION SLAVE, REPLICATION CLIENT)
• Binary logging is not enabled (log_bin = OFF)

Duplicate byos-N records

You pre-registered a server (e.g. bintrail-demo-tiny) via the dashboard or POST /api/v1/servers, then started the agent with a numeric --server-id <N>. Now your dashboard shows two cards for the same MySQL host:

• The pre-registered card (bintrail-demo-tiny) sits at 0 events with onboarding_step=waiting_for_agent.
• A duplicate card named byos-<N> (e.g. byos-202) accumulates the real event count.

This happens because the agent's first metadata batch hit ingest._auto_register_server before any binding to the pre-registered record was established. The fix has two parts.

1. Prevent recurrence (going forward)

Add --server-uuid <UUID> to the agent's systemd unit. The UUID is the pre-registered server's id from the dashboard URL (/app/servers/<UUID>) or GET /api/v1/servers:

ExecStart=/usr/local/bin/bintrail agent \
    --api-key bt_live_… \
    --endpoint wss://api.dbtrail.com/v1/agent \
    --server-id 202 \
    --server-uuid 183819c0-5742-400a-b1ae-cfb4f63dbdd4 \
    --source-dsn …

Reload and restart: sudo systemctl daemon-reload && sudo systemctl restart bintrail-agent. From this connect onward the WS handshake binds to your pre-registered record.

2. Clean up existing duplicates

The WS handshake fix doesn't migrate the event history. To redirect new events from byos-<N> to your pre-registered record, decommission the duplicate and reassign its bintrail_id:

BEGIN;

-- Decommission the duplicate so it stops matching ingest lookups
UPDATE <tenant_schema>.registered_servers
SET status = 'decommissioned'
WHERE name = 'byos-202';

-- Reassign the bintrail_id to the pre-registered record
-- (the partial unique index allows this once byos-202 is decommissioned)
UPDATE <tenant_schema>.registered_servers
SET bintrail_id = '202'
WHERE name = 'bintrail-demo-tiny';

COMMIT;

The uq_registered_servers_bintrail_id index is partial on WHERE status != 'decommissioned', so the decommission + reassign is safe in one transaction.

Within seconds the next POST /v1/events batch matches the pre-registered record (via _resolve_server's bintrail_id fallback) and events start accumulating in the correct bt_<server_uuid> database on the metadata EC2.

The duplicate's historical events stay in their original bt_<duplicate_uuid> database — they're orphaned but not destroyed. Run DROP DATABASE bt_<duplicate_uuid> on the metadata EC2 to reclaim disk space when you're ready.

Background: see BYOS Architecture → Server identity.

Authentication

"Invalid API key" error

• Verify the key hasn't been revoked (check Dashboard → Settings → API Keys)
• Check for extra whitespace or missing characters in the key
• Ensure the key format matches: bt_live_<32 hex chars>
• Confirm the key hasn't expired

"Not a member of this tenant" error

The authenticated user is not a member of the tenant specified in the X-Tenant-ID header. This can happen if:

• You're using the wrong tenant ID
• Your membership was removed by an admin
• You're using a JWT (not an API key) and omitted the X-Tenant-ID header

Claude connection

Tools not appearing

1. Verify your API key is valid and not revoked
2. Check the connection URL: https://api.dbtrail.com/mcp
3. Ensure the Authorization header is set correctly
4. Restart your AI app after configuration changes

"Permission denied" on tools

Your role doesn't have the required permission. Connecting Claude requires mcp:connect (analyst and above — viewers do not have this). Specific tools require additional permissions:

• list_servers → mcp:connect (analyst and above)
• query → query:execute (analyst and above)
• recover → recover:execute (operator and above)
• status → status:read (analyst and above)

Rate limiting

"Rate limit exceeded" (429)

You've exceeded the rate limit for your plan. Wait and retry, or upgrade your plan for higher limits.

Getting help

If you can't resolve an issue using this guide, contact support at support@dbtrail.com with:

• Your tenant ID
• The server ID (if applicable)
• A description of the issue
• Any error messages you received