- Will not launch, quits at launch, Gatekeeper: the app will not open
- Refused, timed out, stuck on Connecting: a connection fails
- A certificate is rejected: TLS and certificates
- A driver is missing, rejected, or stale: a plugin will not install or load
- The tunnel never comes up: SSH tunnel failures
- Rows are missing, or a query is cancelled under you: a query is slow
- A save is refused: edits will not save
- You need the log, or you are filing a bug: logs and diagnostics
The app will not open
- Too old a macOS: 13.0 (Ventura) is the minimum.
- macOS refuses to open it: the copy was damaged or stripped of its signature. Confirm with
spctl -a -vvv /Applications/TablePro.app, then re-download or runbrew install --cask tablepro. - Opens then quits: attach the crash report from Console.app to an issue.
- Opens straight into a connection: startup is on Reopen Last Session. Switch to Show Welcome Screen in Settings > General.
A connection fails
A failed connect paints the connection’s window with Could not connect to…, the driver’s own message, and three buttons: Try Again, Manage Connections…, Copy Details. That holds for a connect started from the welcome window or the connection switcher too: the error lands in the window, not in an alert.
- Refused means something answered and said no: the server is not listening on that port, or it is bound to
127.0.0.1only. Timed out means nothing answered, which points at a firewall, a security group or a VPN. Tell them apart withnc -zv host port. - Still on Connecting: after 12 seconds on one step the pane says “This is taking longer than usual.” Cancel gives up at once. Reopen Last Session brings that connection back as Not connected without dialing it; a connect that fails on its own dials again.
- Disconnected from
…after a run of Reconnecting to…: the tunnel, the proxy or the server dropped, and every try failed or you clicked Cancel. The pane names the cause; fix it and click Reconnect. See When a connection drops. - On macOS 15 and later, a host at a local network address (
192.168.x.x,10.x.x.x,.local) needs the Local Network permission. Without it the window reads Local Network Access Required and names the host it could not reach: the database, the SSH server or jump host, or the SOCKS proxy. Open System Settings takes you to Privacy & Security; turn TablePro on under Local Network, then click Try Again. Copy Details still holds the driver’s message. Loopback and internet hosts are unaffected. - Authentication failures are engine-specific. See PostgreSQL, MySQL or SQL Server.
TLS and certificates
A handshake failure names the cause and the SSL Mode to switch to, with the driver’s original error underneath. The ladder is Disabled, Preferred, Required, Verify CA, Verify Identity. Every handshake error string and the mode that fixes it is on SSL/TLS.A plugin will not install or load
A plugin that fails any of its checks appears as a banner in Settings > Extensions with the reason.”Plugin code signature verification failed: …”
The bundle is not signed by TablePro, is unsigned or ad-hoc signed, or was altered after signing, and there is no override. Download it again from the registry.”Plugin checksum does not match expected value”
The download does not match the SHA-256 in the registry manifest. Retry the install. A second failure means the manifest and the file disagree, so file an issue.”Plugin was built for PluginKit version …; this release of TablePro needs version …”
This plugin predates the app’s current driver interface. TablePro fetches a compatible build on its own, retrying after 30 seconds, then 5 and 10 minutes, five attempts in all. Click Update Now in the banner. A plugin that needs a newer app offers Check for Updates… instead, which reads Update Available… or Relaunch to Update once that app is waiting.”Couldn’t reach the plugin registry”
A network problem, not a bad plugin. Retry once you are online.”The … plugin is not installed”
A saved connection’s driver is missing. The failure screen offers Install Plugin…. Removing a plugin needs a relaunch, offered as Relaunch in the banner. Plugins you installed live in~/Library/Application Support/TablePro/Plugins. See Plugins.
SSH tunnel failures
”SSH host key verification failed”
The server presented a key that does not match the stored one, or you declined the prompt. Trusted keys are in~/Library/Application Support/TablePro/known_hosts. Accept a changed key only when you know what changed it, such as a rebuild or a rotation.
”No available local port for SSH tunnel”
The tunnel binds a local port between 60000 and 65000 and found none free. List what holds them withlsof -nP -iTCP -sTCP:LISTEN, quit those processes, reconnect.
Failures on the far side start with “The SSH server could not reach …”. Those, the authentication rejections, and a server limited to algorithms TablePro no longer supports (“TablePro and the SSH server have no … in common.”) are in SSH Tunneling.
A query is slow, or the results stop short
Your SQL reaches the server exactly as you wrote it. The cap applies to the rows read back, so a query carrying its ownLIMIT, FETCH FIRST or TOP is never touched, and EXPLAIN, SHOW,
writes and DDL are never capped. The read itself stops at the cap on MySQL, MariaDB, PostgreSQL,
CockroachDB, Redshift, SQLite, MSSQL, Oracle, Cassandra, Redis, DynamoDB, BigQuery, Snowflake, Trino, Presto,
ClickHouse, SAP HANA and MongoDB, so the rest of the result never crosses the network. Cloudflare D1, LibSQL,
Etcd, DuckDB, Elasticsearch, Typesense, SurrealDB, Beancount and Dameng still read the whole result and keep the
first rows. A plan that has to finish before it can return a first row, a sort with no index or a
GROUP BY, runs to completion on the server either way. Both numbers are in Settings > Data
(Data settings).
A capped result offers Fetch All in the status bar, and Query > Execute Query Without Limit runs one query with the cap off. Browsing a table pages instead of capping.
A query that runs past the timeout in Settings > General is cancelled (Settings); cancel one yourself with Cmd+.. A changed timeout reaches new connections only, so reconnect after changing it or the old value stays in force with nothing to say so.
Edits will not save
- The connection is at the Read-Only safe mode level, which disables cell editing, row changes and import.
- A result is editable only when it came from one table. Joins, comma joins, subqueries in
FROM, CTEs,UNION,EXCEPTandINTERSECTare read-only. - Select the primary key, unaliased. A key that is renamed with
ASor left out blocks the whole save. - Generated columns are left out of every
INSERTandUPDATE, so a value typed into one never reaches the server. - A table with no primary key is matched on every original column value, and the save fails when that matches no row. Someone else usually edited it first.
Logs and diagnostics
Logging goes to OSLog undercom.TablePro, with four drivers on subsystems of their own: com.TablePro.PostgreSQLDriver, com.TablePro.RedisDriver, com.TablePro.CassandraDriver, com.TablePro.OracleDriver. Filter on the subsystem in Console.app, or read the last half hour in Terminal:
~/Library/Application Support/TablePro, preferences in ~/Library/Preferences/com.TablePro.plist. Settings > General has Reset All Settings to Defaults.
Neither copy button includes a password. Copy Details carries the host, the database name, the SSH host, and any non-default port; Copy Diagnostic Info adds the user name.
Filing a bug report
Help > Report an Issue opens the issue tracker. A report that gets fixed quickly carries:- The version from TablePro > About TablePro, your macOS version, and whether the Mac is Apple Silicon or Intel
- The engine and server version, plus the plugin version from Settings > Extensions
- The error pasted from Copy Details or Copy Diagnostic Info, not retyped
- What you ran, what happened, and what you expected. Add the log lines when the failure left no dialog

