Troubleshooting

This page collects the errors Querybara reports in situations you are likely to meet, with the message as Querybara shows it and the fix. Messages in angle brackets, such as <host>, stand for the values Querybara fills in. Most errors come with a hint line; the hint is often the fix.

Start with Test Connection in the app or querybara test on the command line: both run the connection step by step and stop at the step that fails.

Connections

TLS negotiation failed

TLS negotiation with <host>:<port> failed: <reason>

With TLS on in verify-full mode (Verify certificate and host name), the certificate must be signed by a trusted authority and name the host you connect to. The hint depends on the reason:

Hint	Fix
Set the server’s CA certificate in the TLS settings, or use TLS mode ‘require’ to encrypt without verifying	The server uses a self-signed or private CA certificate. Add the CA certificate to the profile’s TLS settings
The certificate does not name this host: set the TLS server name, or use TLS mode ‘verify-ca’	You connect by a name or address the certificate does not list. Set the server name the certificate uses
The server certificate is outside its validity period; renew it or check this computer’s clock	Renew the certificate, or correct the computer’s date and time
Check that the server has TLS enabled and that the TLS mode and certificates in the profile match it	The server may not accept TLS at all, or the profile’s certificates do not match it

On the command line, --tls <mode> sets the mode for one run, for example --tls verify-ca.

Weaker modes

require encrypts the connection but does not check who is on the other end. Prefer adding the CA certificate.

Test Connection fails at the TLS step on a local server

When Test Connection fails at the TLS handshake with TLS on, the dialog adds:

The TLS handshake failed. If the server has no TLS (common for local servers), set TLS to “Disable TLS” on the TLS tab.

Many local and development servers run without TLS. Open the TLS tab and choose Disable TLS. New connections start with TLS off, so this happens when TLS was turned on by hand, by a URI, or by an SRV record or Elastic Cloud ID.

A server that needs TLS refuses the CLI

A connection URI with no TLS settings connects without TLS. For a server that requires TLS, add the mode to the URI, such as ?sslmode=verify-full, or pass --tls verify-full. See Global options and environment.

The host cannot be reached

Message	Hint
Could not resolve the host name of <host>	Check the host name for typos and that this computer can reach your DNS (VPN, network)
Connection to <host> was refused	Check that the server is running and listening on this host and port, and that no firewall blocks it
<host> is unreachable from this computer	Check your network or VPN connection, or connect through an SSH tunnel
Timed out connecting to <host>	Check the host, port and firewall rules, or raise the connect timeout
The connection to <host> was closed unexpectedly	The server or something in between closed the connection; check the TLS mode and the server log

An SRV record cannot be looked up

The SRV record <name> could not be looked up on this computer

For mongodb+srv connections through an SSH tunnel or proxy, SRV and TXT records are looked up on your computer, not through the tunnel. Make the name resolvable on your computer, or connect with a host list of the members as the SSH server sees them.

SSH host keys

The host key has changed

In the app, connecting opens Warning: the SSH host key has changed and Querybara does not connect. On the command line:

WARNING: the host key of the SSH server <host> has CHANGED (expected <key>, got <key>). Someone could be intercepting this connection (a man-in-the-middle attack), or the server was reinstalled. Querybara did not connect.

The server presented a different key from the one in Querybara’s known_hosts. Ask the server’s administrator whether its host key changed.

• If it did, remove the remembered key: in the dialog, tick The administrator confirmed that the host key changed and choose Remove the remembered key. Querybara then asks whether to trust the new key; compare its fingerprint with the one the administrator gives you.
• If it did not, do not connect. Someone may be intercepting the connection.

The CLI always refuses a changed key. Connect from the app to remove the old key as above, then run the command again.

A new host key on the command line

The host key of the SSH server <host> is not known yet (<fingerprint>)

The CLI met an SSH server it has not seen, with no terminal to ask in. Compare the fingerprint with the one the server’s administrator gives you, then run again with --ssh-accept-new to trust and remember it. You can also connect once from the desktop app and choose Trust and remember; the CLI reads the same known_hosts file.

Passwords

No secure storage on Linux

The connection dialog shows No keychain or secret service is available on this system, and saving a password says:

This system has no secure storage for passwords. Choose "Remember for this session" or "Ask every time".

Querybara saves passwords only in the OS keychain. On Linux that needs a running and unlocked secret service such as GNOME Keyring or KWallet. Install and unlock one, or use Remember for this session or Ask every time.

The CLI cannot read a saved password

The password for profile "<name>" is not available

The desktop app sealed the password with the OS keychain, which the CLI cannot open; or the profile asks for its password every time. Set QUERYBARA_PASSWORD_<NAME> or QUERYBARA_PASSWORD, or run in a terminal to be asked. See Global options and environment.

Schedules

Schedules run only while Querybara is open. Each run’s message is in the schedule’s run history in the Schedules panel.

Message	What to do
The password of <name> is not saved, and a scheduled run cannot ask for it	Edit the connection and choose Save in the OS keychain for the password, or type it earlier in the session
The backup passphrase is not saved; edit the schedule and enter it again	Edit the schedule and enter the backup’s passphrase again
The schedule cannot be read by this version of Querybara; edit and save it again	Edit the schedule and save it

Closing Querybara asks about schedules

With a schedule on, closing Querybara asks first, because schedules do not run while it is closed. The question names the next run and any run going now, which closing stops. Missed runs are caught up or skipped when Querybara opens again, as each schedule says.

Tick Don’t ask again to stop the question. To bring it back, turn on Ask before closing in the Schedules panel.

Parquet files

Message	What to do
This Parquet file uses a compression Querybara does not read (<codec>)	Rewrite the file with Snappy, ZSTD, GZIP, Brotli or LZ4
ZSTD compression needs Node.js 22.15 or later	On the command line, run the CLI with Node.js 22.15 or later, or use another --codec
A gzipped Parquet file is one other tools cannot read	Leave out --gzip. Parquet compresses its own pages: use --codec zstd for smaller files
This Parquet file is encrypted	Decrypt it with the tool that wrote it

Files compressed with LZO are refused with the first message.

The CLI

A statement needs confirmation

Statement <n> needs confirmation: <reason>

The statement is risky, such as a DELETE without WHERE, or the profile is a production or confirm-writes profile, and there is no terminal to ask in. Pass --yes to run it without asking, or run the command in a terminal. Scripts read from stdin always need --yes.

A statement writes to a read-only profile

Statement <n> writes, but "<name>" is read-only

The profile is locked read-only, or you passed --read-only. Unlock the profile in the app, or use another profile to write.

The command does not support the engine

"<name>" is a MongoDB connection; this command works with PostgreSQL, MySQL and MariaDB

compare, data-compare, ddl, import, export and run-file work with the SQL engines only. Use querybara test and querybara query with MongoDB, Redis and Elasticsearch connections; see the feature matrix.

Backups

Message	What to do
This backup is encrypted: enter its passphrase to open it	Give the passphrase; on the command line, set QUERYBARA_BACKUP_PASSPHRASE
The passphrase is wrong, or the backup header was modified	Check the passphrase. Without the right one, the archive cannot be opened
The backup was modified or is damaged: <part> failed its integrity check	The file changed after it was written. Use another copy of the backup
This file is not a Querybara backup archive	The file is not a .qbak archive

Installing and starting

macOS will not open a test build

Test builds are not signed, so macOS asks you to allow them in System Settings → Privacy & Security the first time they open. Release builds are signed and notarised when the signing secrets are set.

Querybara cannot open its data

The local store in <folder> could not be opened: <reason>

The dialog is titled Querybara cannot open its data. Querybara could not open querybara.db in its data folder, and quits; the reason after the colon says why. See Data and settings locations.

Updates do not install

The About box says why updates are off; see Updates and channels. deb and rpm updates need the desktop’s graphical administrator prompt (polkit’s pkexec); without one, install the new package by hand.

Related

• querybara test
• Security model
• Exit codes