Documentation

Common issues and how to resolve them.

Connection refused

If you see "Connection refused" when connecting to a database:

• Verify the host and port are correct
• Ensure the database server is running and accepting connections
• Check firewall rules — the port must be open for inbound connections
• For remote databases, try connecting via SSH tunnel

SSL/TLS errors

• Self-signed certificates — set SSL mode to require (skips CA verification) or provide your CA certificate in the connection form
• Certificate expired — update the server certificate or set SSL mode to require temporarily
• SSL not supported — set SSL mode to disable (not recommended for remote connections)

Keisen supports five SSL modes: disable, prefer, require, verify-ca, and verify-full.

Authentication failed

• Double-check username and password — credentials are case-sensitive
• For PostgreSQL, verify the pg_hba.conf allows your connection method
• For MySQL, ensure the user has permissions from your IP address
• Try re-entering the password in the project edit dialog

"Database does not exist"

• Verify the database name is spelled correctly
• For PostgreSQL, list databases with \l in psql
• For MySQL, list databases with SHOW DATABASES in the mysql client
• For SQLite, ensure the file path is correct and the file exists

Slow queries or timeouts

• Run EXPLAIN ANALYZE on your query to identify bottlenecks — Keisen's EXPLAIN view makes this visual
• Check if the query needs an index
• For large result sets, Keisen uses virtual scrolling — but the initial fetch may take time
• Consider adding LIMIT to exploratory queries

SSH tunnel not connecting

• Verify the SSH host, port (default: 22), and username
• If using key-based auth, ensure the private key is in OpenSSH format
• Check that the SSH server allows TCP forwarding (AllowTcpForwarding yes in sshd_config)
• If the tunnel connects but the database doesn't, verify the database host is reachable from the SSH server (often localhost or 127.0.0.1)

AI not responding

• Check your internet connection — AI features require connectivity
• Verify your plan includes AI tokens (Lite plan has no AI)
• Check if your monthly token quota is exhausted — the token count resets at the start of each billing cycle
• Try closing and reopening the AI panel

App won't start or crashes on launch

• macOS — if you see "damaged" or "unidentified developer", right-click the app and select Open, or go to System Settings > Privacy & Security and allow it
• Windows — if SmartScreen blocks it, click "More info" then "Run anyway"
• Linux — ensure the AppImage has execute permissions: chmod +x Keisen.AppImage
• Try deleting the app's data directory and restarting (this resets all local settings)

Credentials not persisting

• If credentials are lost after an update, re-enter them in the project edit dialog

Data not saving after inline edit

• Ensure the project is not in read-only mode
• The table must have a primary key for row identification
• Check the change tracker in the bottom bar — uncommitted changes appear as a badge
• Hold the Apply button to commit changes