Troubleshooting & FAQ

This page covers the most common issues users encounter and how to resolve them.

Connection Problems

"Connection refused" or timeout

  • Check the host and port. Ensure the database server is running and accepting connections on the configured port. Use telnet <host> <port> or nc -zv <host> <port> from a terminal to verify network reachability.
  • Firewall rules. Cloud databases (AWS RDS, GCP Cloud SQL, Azure) often restrict inbound connections to specific IP ranges or VPCs. Verify your IP is allowlisted.
  • SSL/TLS requirements. Some servers require encrypted connections. Check if your provider mandates sslmode=require or similar.
  • AWS RDS / private CA. If "Test connection" succeeds but the connection drops shortly after with a TLS handshake error, the system trust store likely doesn't trust the database's CA. Paste the path to a PEM bundle in the connection's CA Certificate field — for AWS RDS, use https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem. See Connections → TLS & CA Certificates.

"Authentication failed"

  • Double-check username and password. With Save passwords in Keychain checked, passwords are stored in the OS keychain — if the keychain entry was deleted externally, re-enter the password in the connection editor and save.
  • For PostgreSQL, verify pg_hba.conf allows your auth method (usually md5 or scram-sha-256).
  • For MySQL, ensure the user has GRANT privileges for the target host (e.g., 'user'@'%' vs. 'user'@'localhost').

"Too many connections"

Your database server has a connection limit. Tabularis keeps a connection pool per open profile: up to 10 connections for MySQL/MariaDB, up to 10 for PostgreSQL by default (configurable with the built-in PostgreSQL driver's Pool Max Size setting in Settings → Plugins, up to 64), and up to 5 for SQLite. Close unused connections from the sidebar (right-click → Disconnect) or increase the server's max_connections setting.

SQLite: "database is locked"

SQLite allows only one writer at a time. If another process (or another Tabularis tab) holds a write lock, you will see this error. Close the other writer or enable WAL mode (PRAGMA journal_mode=WAL;) for better concurrency.

SSH Tunnel Problems

"Host key verification failed"

Tabularis checks ~/.ssh/known_hosts. If the server's host key changed (e.g., after a rebuild), remove the old entry:

ssh-keygen -R <hostname>

Then reconnect — Tabularis will trust the new key on first use.

"Permission denied (publickey)"

  • Verify the private key path is correct in the SSH profile.
  • Check file permissions: chmod 600 ~/.ssh/id_rsa.
  • If using a passphrase-protected key, ensure the passphrase is entered (or saved in keychain).
  • For key-only auth (no password), Tabularis uses the system ssh binary. Test manually: ssh -i <key_file> <user>@<host> to see the exact error.

Tunnel connects but queries time out

The SSH tunnel is up but the database is unreachable from the bastion. Verify the remote host and remote port in the connection settings point to a host the bastion can reach. SSH into the bastion manually and test: nc -zv <db_host> <db_port>.

AI Assistant Problems

"API key invalid" or "401 Unauthorized"

  • Re-enter your API key in Settings → AI. Keys are stored in the OS keychain.
  • For OpenRouter, ensure your account has credits.
  • For Ollama, no API key is needed — verify the service is running: curl http://localhost:11434/api/tags.

AI generates incorrect column names

Ensure Tabularis has loaded your schema. Connect to the database and expand at least one table in the sidebar before asking the AI. The schema snapshot is built from cached metadata — if the cache is empty, the AI has no context.

Performance

Data Grid is slow with wide tables

Tables with 50+ columns can slow down rendering. Query only the columns you need with an explicit SELECT list in the SQL editor. Reducing resultPageSize in Configuration also helps.

Editor autocomplete is delayed

Autocomplete loads table and column metadata on first trigger. For databases with thousands of tables, the initial load can take a few seconds. Subsequent completions are instant because the metadata is cached.

Logs & Debugging

Tabularis keeps application logs in an in-memory buffer (no log file is written to disk). Access them from Settings → Logs.

Action How
View logs Settings → Logs tab
Export logs Click Export in the Logs tab to save to a file
Clear logs Click Clear to reset the log buffer

The default log level is Info. For more detail, launch Tabularis from a terminal with --debug, or set RUST_LOG (for example RUST_LOG=debug); since v0.28.0 both raise the level, and --debug includes the SQL statements logged by sqlx. See CLI.

When reporting a bug, export the logs and attach them to your issue on GitHub.

Installation Problems

Linux AppImage opens a black window

On distributions with a recent Mesa (Arch, Solus, …), AppImages of v0.13.3 through v0.18.0 could open a black window: the bundle shipped a stale libwayland that the host libEGL bound to, and WebKitWebProcess aborted with EGL_BAD_PARAMETER. Fixed in v0.19.0 — the AppImage no longer bundles libwayland at all. If you're stuck on an affected version, download the v0.19.0 (or newer) AppImage from the releases page.

Tabularis Web Problems

These apply to Tabularis Web, started with tabularis web or from the container image.

The server does not start

  • Address already in use: choose a free port, for example --port 8081. Tabularis does not look for one itself.
  • Non-loopback bind rejected: a remote bind needs --auth, --public-url and --allowed-origin; see Remote Access & Reverse Proxy.
  • Password or proxy secret rejected: set TABULARIS_WEB_PASSWORD (12+ characters) or TABULARIS_WEB_PROXY_SECRET (32+ characters) in the service's environment.
  • Web UI assets not found: reinstall the complete package.

The browser cannot sign in or keeps losing the session

Response Likely cause Fix
401 locally The one-time access URL expired or was already used Restart tabularis web and let it open a fresh URL; don't bookmark it
401 remotely Wrong password, or the proxy doesn't replace both identity headers Check the password or the proxy configuration
403 Unexpected Host or Origin, or an action a remote session isn't allowed to run Check the public URL, the allowed origins and that the proxy keeps the Host header
429 Too many failed sign-ins from this client Wait five minutes, then use the right credentials
Progress stops or disconnects The proxy drops WebSockets Enable WebSocket upgrades and longer idle timeouts on the proxy

Features fail after signing in

  • Saved passwords are missing: the server runs under another account or home folder, or can't unlock its credential store. Copying configuration files does not copy credentials.
  • An import, export, dump or BLOB download expired: start it again from the UI. Transfer links are short-lived and often single-use.
  • A large query fails: results are capped at 10,000 rows per page and 16 MiB per response. Paginate, select fewer columns or export.
  • A plugin won't start: the plugin release must support the server's operating system and architecture. Check its startup error in the server logs.
  • Clipboard, notifications, new tabs or links are blocked: allow them in the browser for the Tabularis site.

FAQ

Where are my connections stored?

Connection profiles are in connections.json inside the app config directory. Passwords are in your OS keychain when Save passwords in Keychain is checked on the connection; otherwise they are saved in connections.json too. Since v0.23.0 the folder can be relocated from Settings → Storage or with the TABULARIS_DATA_DIR environment variable; see Configuration. See Security & Credentials for details.

Can I use Tabularis with a read-only database user?

Yes. A read-only database user is the most reliable way to prevent writes. Tabularis has no per-connection read-only toggle; marking the connection as production adds a confirmation before any statement that isn't provably read-only (see Production Write Guard), and MCP Read-Only Mode blocks writes from AI clients.

How do I reset Tabularis to default settings?

Delete the app config directory:

  • Linux: ~/.config/tabularis
  • macOS: ~/Library/Application Support/tabularis
  • Windows: %APPDATA%\tabularis

Restart Tabularis. It starts with default settings.

Does Tabularis send telemetry?

No. The desktop app contains no analytics or telemetry code. Network requests are limited to your databases, update checks, the plugin registry, and the AI provider you configure. No database content or query data is ever transmitted to Tabularis.