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)

Stream issues

Stream not capturing changes

1. Verify the stream is active: Servers → your server → Status
2. Check that binary logging is enabled and uses row format:

   SHOW VARIABLES LIKE 'log_bin';        -- Must be ON
   SHOW VARIABLES LIKE 'binlog_format';  -- Must be ROW

3. Confirm the bintrail MySQL user has replication privileges
4. Check if schema/table filters are excluding the tables you expect

Missing or incomplete changes for specific tables

If some tables show no changes or unreliable data while others work fine, check that those tables use InnoDB and have a primary key:

-- Check a specific table's engine and keys
SHOW CREATE TABLE your_schema.your_table;

• Non-InnoDB tables (e.g., MyISAM) are non-transactional — failed or interrupted statements can produce partial row events that dbtrail cannot reliably interpret. Convert them: ALTER TABLE your_schema.your_table ENGINE=InnoDB;
• Tables without a primary key require full table scans for row identification during binlog processing and may be ambiguous when duplicate rows exist. Add a primary key: ALTER TABLE your_schema.your_table ADD PRIMARY KEY (your_column); (replace your_column with the column or columns that uniquely identify each row).

Caution: ALTER TABLE on large tables can lock the table and take significant time. Use an online schema change tool like pt-online-schema-change or gh-ost for production databases.

See the Quick Start prerequisites for queries that find all affected tables at once.

Stream shows "disconnected"

The agent lost the MySQL connection. It will auto-retry. Common causes:

• MySQL server restart
• Network interruption
• MySQL connection timeout

The stream will resume from its last checkpoint when the connection is restored.

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