Network

Connection refused / timeout

Wrong host or port — double-check against the engine's default port
Firewall / security group blocking the port
Database bound to 127.0.0.1 only — use an SSH tunnel

Drops after idle

Network or bastion killing idle TCP. RaisDB retries SSH with exponential backoff; for the DB link, lower the idle timeout in the engine or keep the connection warm.

Authentication

Wrong credentials

Re-enter username/password and Test again.

Missing privileges

The user needs CONNECT (or engine equivalent) on the target database.

PostgreSQL `pg_hba.conf`

The line for your IP must permit the user/database. Edit pg_hba.conf and reload.

Connecting as SYS automatically enables SYSDBA mode — no manual flag needed. See JDBC Agent Bridge → Oracle specifics.

SSL handshake

Mismatched SSL mode

Self-signed cert with require → switch to verifyca and provide a CA bundle
Hostname mismatch → either fix the cert or relax to verifyca

See SSL / TLS for the five modes.

JDBC agent errors

JRE not found

Install JRE 11+ and restart RaisDB. Verify with java -version.

Driver download blocked

Switch to the China mirror (Oracle / Dameng). Kingbase has no mirror — retry or download manually.

Driver version mismatch

Delete ~/.raisdb/drivers/<engine>/ and re-download from the banner.

Oracle service not found

Leave the database name blank — RaisDB auto-tries XE / FREE / ORCL / XEPDB1 / FREEPDB1.

Test vs real connect

If Test succeeds but the sidebar connection fails, remember the difference:

Test creates a throwaway pool, pings, then tears it down
Clicking a connection in the sidebar creates the real persistent pool

Clear stale state with raisdb doctor or restart the app.

Connection Troubleshooting