Error Reference

No active database connection. Open SQLAgent and connect to a server before running queries or browsing tables.

The database server refused the connection. Common causes:

• The server is not running or not reachable from your network
• Wrong host, port, or credentials
• Firewall blocking the port
• Cloud database requiring IP whitelisting

The server rejected your credentials. Double-check your username and password. For MySQL, ensure the user has permission to connect from your IP address.

The server requires an encrypted connection. Enable SSL in the connection form. You may also need to provide a CA certificate if the server uses a self-signed cert.

SQLAgent couldn't reach the server within the time limit. Check that the host and port are correct, your internet connection is stable, and no firewall is blocking traffic.

The connection to the database was dropped unexpectedly. SQLAgent will attempt to reconnect automatically (up to 3 times). If reconnection fails, check your network and reconnect manually.

Auto-reconnect failed. The server may be down or your network changed. Disconnect and reconnect manually from the connection form.

You enabled SSH tunneling but didn't provide a hostname for the SSH server. Enter the SSH server address (e.g. bastion.example.com).

Provide the SSH username to authenticate with the tunnel server.

The SSH private key file doesn't exist at the specified path. Check the file path and ensure the key file is readable (e.g. ~/.ssh/id_rsa).

The SSH connection couldn't be established in time. Verify the SSH host and port are correct, and that the server allows your key or password authentication.

SQLAgent couldn't find a free local port to forward traffic through. This is rare — try closing other apps that may be using many ports, or restart SQLAgent.

The SQLite database file does not exist at the specified path. Check that the path is correct and the file hasn't been moved or deleted.

The file exists but is not a readable SQLite database. It may be corrupted, encrypted, or not a database file at all. Verify the file by running file yourfile.sqlite in Terminal.

You don't have permission to read this file. The validation banner shows the file owner. You may need to adjust file permissions with chmod or run SQLAgent as a user with access.

The database file is readable but not writable. You can browse and query data, but INSERT, UPDATE, and DELETE operations will fail. To enable writes, check the file permissions and ownership.

Another process has an exclusive lock on the SQLite database. Close other applications using the file (e.g. another database client, a running server, or a Wrangler dev instance) and try again.

Your Cloudflare API token is invalid or doesn't have D1 permissions. Go to the Cloudflare dashboard and create a token with D1 Edit permissions.

The API token exists but lacks the required D1 scope. Edit your token in Cloudflare and add the Account → D1 → Edit permission.

The D1 database UUID doesn't match any database in your account. Copy the correct ID from Workers & Pages → D1 in your Cloudflare dashboard.

You've hit the Cloudflare API rate limit. Wait a few minutes before making more requests. Consider batching your queries to reduce API calls.

You're connected to D1 but haven't selected a database yet. Go back to the database list and select one.

D1 requires internet access to communicate with Cloudflare's API. Check your network connection.

SQLAgent can't connect to api.cloudflare.com. This could be a DNS issue, a firewall, or a Cloudflare outage. Check Cloudflare Status.

SQLite uses || for string concatenation instead of CONCAT().

first_name || ' ' || last_name

SQLite uses datetime('now') instead of NOW().

SELECT datetime('now');

SQLite uses date('now') instead of CURDATE().

SELECT date('now');

Use IFNULL() or COALESCE() in SQLite instead of ISNULL().

SELECT IFNULL(column, 'default') FROM table;

Use strftime() in SQLite instead of DATE_FORMAT().

SELECT strftime('%Y-%m-%d', date_column) FROM table;

• Tables: SELECT name FROM sqlite_master WHERE type='table'
• Columns: PRAGMA table_info('table_name')
• Indexes: PRAGMA index_list('table_name')

Use PRAGMA table_info('table_name') instead of DESCRIBE.

SQLite doesn't support TRUNCATE TABLE. Use DELETE FROM table_name instead.

In SQLite, use INTEGER PRIMARY KEY for auto-incrementing IDs. The AUTOINCREMENT keyword is optional and behaves differently than MySQL's AUTO_INCREMENT.

Your query took longer than the configured timeout. Try adding a LIMIT clause, more specific WHERE conditions, or increase the timeout in Settings.

The SQL query contains a syntax error or references a non-existent table/column. Check the error detail for the specific SQL issue.

The database name doesn't exist on this server. Use the database list to see available databases.

The table doesn't exist in the current database. It may have been dropped or renamed. Refresh the table list to see current tables.

An inline edit couldn't be saved. This can happen if the row was modified by another client, a constraint was violated, or the connection was lost.

The AI assistant needs an API key. Go to Settings → AI Assistant and add your Anthropic, OpenAI, or xAI key.

Your API key was rejected by the provider. Verify it in Settings → AI Assistant. Make sure you're using the correct provider (Anthropic vs OpenAI vs xAI).

The AI returned an unexpected format. Try rephrasing your prompt or switching to a different model in Settings.

The TCP connection to MySQL was interrupted mid-communication. This usually means the server closed the connection (idle timeout, crash, or network drop). SQLAgent will attempt to reconnect automatically.

Received a malformed packet from the MySQL server. This can indicate a protocol mismatch, network corruption, or an incompatible server version.

SQLAgent couldn't establish a TCP connection to the MySQL host. Verify the host and port, and check that no firewall is blocking the connection.