Troubleshooting

Read the logs

DevDb writes what it does to the DevDb output channel.

1. Open the Output panel (View > Output).
2. In the list at the top right, select DevDb.

The log shows which zero-config sources DevDb checked and why a source was skipped. Add the log to a bug report.

For more detail in the developer console, set Devdb.showDebugInfo to true, then run Developer: Toggle Developer Tools.

MCP server logs are in ~/.devdb/mcp-log.txt. See MCP Server.

DevDb does not start

Workspace trust

DevDb does not run in Restricted Mode. It runs project tools such as php artisan, bin/rails and python manage.py, so it needs a trusted workspace.

To trust the workspace, click Restricted Mode in the status bar, then select Trust.

DevDb does not find my database

1. Open the DevDb output channel and read why detection failed.
2. Make sure that your database server is running and that your app can connect to it.
3. Check the requirements for your framework in Zero-Config Detection. For example, Django needs venv/ in the workspace root, and DDEV needs ddev start.
4. If the app is in a subfolder, set Devdb.customBasePath.
5. Click the refresh button in the DevDb panel.
6. If detection still fails, use a .devdbrc file.

SQLite

Native and WASM SQLite

DevDb first loads the native SQLite driver. If the native driver cannot load, DevDb uses a WebAssembly (WASM) SQLite. This happens, for example:

• With the universal package from Open VSX (Cursor, Windsurf, VSCodium) on macOS, Windows or ARM.
• On Linux with glibc older than 2.29.

The DevDb output channel shows which backend DevDb uses:

SQLite backend: native
SQLite backend: wasm (native binary failed to load: ...)

WASM fallback

In WASM mode:

• WAL-mode databases open read-only. WAL is the default in Rails 7.1 and later. If you try to save a change, DevDb shows "SQLite WASM backend opens WAL-mode databases read-only". To edit these databases, install the DevDb package for your platform.
• DevDb does not share file locks with other processes. Do not write from DevDb while your app writes to the same file.

To get the native driver, install DevDb from the VS Code Marketplace, or install the .vsix package for your platform.

"A path to an SQLite database file ... is not valid"

The path in .devdbrc does not point to a file. A relative path is resolved from the folder that contains .devdbrc.

TLS and certificate errors

Error	Cause	Fix
self-signed certificate, self signed certificate in certificate chain	The server uses a self-signed or private certificate	Select Allow self-signed certificate on the direct connection, or add the CA to your system
unable to verify the first certificate	The server does not send the full certificate chain	Fix the server chain, or select Allow self-signed certificate
The server does not support SSL connections	TLS is on, but the server does not use TLS	Clear Enable SSL/TLS
no pg_hba.conf entry ... no encryption	The server requires TLS	Select Enable SSL/TLS
Hostname/IP does not match certificate's altnames	The host name is not in the certificate	Use the host name from the certificate

For SQL Server with a self-signed certificate, set "options": { "trustServerCertificate": true } in .devdbrc.

Redis WRONGPASS or NOAUTH

DevDb stops at once and shows the error from the server.

• WRONGPASS invalid username-password pair: the username or password is not correct. If the server does not use ACL users, leave Username empty.
• NOAUTH Authentication required: the server needs a password. Enter it.
• NOPERM: the ACL user cannot run a command that DevDb needs. Give the user read access to keys (+@read, ~*).

In a redis:// URL, URL-encode special characters in the password.

ClickHouse

• Authentication failed: DevDb checks the password when it connects. Check the username and password.
• Connection reset or TLS error: the port and the protocol do not agree. Use https with port 8443, and http with port 8123. See HTTP or HTTPS.

SSH tunnels

• Unknown SSH host: DevDb shows the fingerprint of the server. Compare it, then click Trust. See Host key trust.
• SSH host key changed: the key of the server is different from the key that you trusted. Find out why before you continue.
• Tunnel fails: set AllowTcpForwarding yes in /etc/ssh/sshd_config on the server.
• Permission denied (publickey): run chmod 600 on the private key, and check the SSH username.

Saved password not found

If DevDb shows "The saved password for ... was not found", the secret storage of your editor does not have the password. Edit the connection and enter the password or connection string again.

Report a bug

Open an issue on GitHub. Add:

• Your DevDb, editor and operating system versions.
• The log from the DevDb output channel. Remove passwords first.
• The steps to reproduce the problem.

For security problems, see Security.