Troubleshooting
Solutions for common connectivity, permission, and configuration issues.
Query Blocked / "Operation not permitted"
Your SQL query was rejected by Safe Mode.
Safe Mode is ON by default
Safe Mode blocks dangerous queries in the Query Editor: DROP TABLE,TRUNCATE, and DELETE/UPDATE without WHERE.
To disable Safe Mode (Power Mode)
Set QUERYGLOW_ALLOW_DESTRUCTIVE=true in your .env file, then restart:
docker compose -f docker-compose.production.yml restartSome operations are ALWAYS blocked
These cannot be enabled: DROP DATABASE,SHUTDOWN, filesystem operations. Use your database's native CLI for these.
Tip: Data Browser buttons (edit/delete single rows) always work regardless of Safe Mode setting.
Connection Refused (ECONNREFUSED)
QueryGlow cannot reach your database host.
Database on same server? Use localhost
Production deployments use network_mode: host, solocalhost or 127.0.0.1 connects directly to your host machine. No special Docker hostname needed.
Check database is running
Verify the database service is active:
sudo systemctl status postgresqlOr for MySQL:
sudo systemctl status mysqlCheck database is listening on correct interface
PostgreSQL: Check listen_addresses in postgresql.conf includes localhost or *.
CockroachDB: Use 127.0.0.1 not localhost
CockroachDB may have IPv6 issues. Use 127.0.0.1 instead of localhost.
SSH Tunnel Errors
Connection fails when using SSH tunneling to reach a remote database.
Authentication Failed
Ensure your SSH private key is in OpenSSH format (starts with -----BEGIN OPENSSH PRIVATE KEY-----). PuTTY keys (.ppk) must be converted first with puttygen.
Encrypted Key Passphrase
If your private key is encrypted, enter the passphrase in the "SSH Passphrase" field. Leave empty for unencrypted keys.
Database Host should be localhost
When using SSH tunneling, set the database "Host" field to 127.0.0.1 or localhost — the tunnel endpoint is on the remote server.
SSH key location tip
You can paste the key contents directly into QueryGlow, or copy from: cat ~/.ssh/id_rsa
Permission Denied (Database)
Connected successfully, but tables won't load or queries fail.
PostgreSQL: Grant schema access
The user must have USAGE on the schema:
GRANT USAGE ON SCHEMA public TO my_user;GRANT SELECT ON ALL TABLES IN SCHEMA public TO my_user;MySQL: Host-specific permissions
MySQL users are defined by user@host. Ensure you have a user for my_user@'localhost' or my_user@'127.0.0.1'.
SQLite: File Not Found or Access Denied
Cannot connect to SQLite database file.
Security restriction: /app/data only
For security, SQLite paths are restricted to /app/data. You cannot access arbitrary paths on the host filesystem.
Copy your database to the data directory
Place your SQLite file inside the QueryGlow data volume:
docker cp ./my-database.db queryglow:/app/data/my-database.dbThen connect using: /app/data/my-database.db
AI Assistant Errors
"API Key not found"
Add the appropriate key to your .env file: OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY. Restart after:
docker compose -f docker-compose.production.yml restart"Rate limit exceeded" (QueryGlow)
QueryGlow limits AI requests to 30 per minute to prevent API cost abuse. Wait a moment and try again.
"Rate limit exceeded" (Provider)
Your AI provider (OpenAI/Anthropic/Google) has its own rate limits. Check your API dashboard or upgrade your plan.
Lost Connections After Update
SESSION_SECRET changed or lost
The SESSION_SECRET encrypts stored database passwords (AES-256-GCM). If it changes, existing connections cannot be decrypted.
Fix: Restore your original .env from backup, or re-create your connections with the new secret.
Still stuck?
Check the container logs for detailed error messages:
docker compose -f docker-compose.production.yml logs -f queryglowIf you can't resolve the issue, open a GitHub issue with the relevant log output.