Skip to content

Troubleshooting

Jump to bottom
zgq edited this page Jul 15, 2026 · 1 revision

Troubleshooting

This page contains current troubleshooting entry points. Before reporting a problem, identify the Chat2DB version, edition, runtime mode, operating system, and database type.

Community does not start

Check the encryption key

Docker, Web, and other non-Desktop runtimes require a valid key before startup:

./script/security/init-community-encryption-key.sh

The default path is:

~/.config/chat2db-community/encryption.key

Do not overwrite the key of an existing installation. A replacement key cannot decrypt previously saved datasource passwords or AI model API keys.

Check logs and the local endpoint

docker logs chat2db-community
curl http://127.0.0.1:10825

Community must remain bound to a loopback address. Do not expose the service publicly to work around a local access problem.

A JDBC driver cannot be downloaded

The runtime may be unable to reach the configured driver download location.

  • Local runtime: place trusted drivers under ~/.chat2db-community/jdbc-lib
  • Docker: place trusted drivers under $HOME/.chat2db-community-docker/jdbc-lib
  • Check the current application.yml for the configured download locations

Custom JDBC drivers are executable Java code. Do not install untrusted JAR files.

Chat2DB cannot connect to a database

Check these items in order:

  1. The database host and port are reachable from the environment running Chat2DB.
  2. The database name, username, password, and authentication mode are correct.
  3. The database permits connections from the Chat2DB source address.
  4. The JDBC driver is compatible with the database version.
  5. Inside Docker, localhost refers to the container itself, not necessarily the host database.
  6. SSH, SSL, proxy, and firewall settings match the actual network path.

See Cannot Connect to a Database for the full checklist.

An AI model request fails

Check:

  • API key, base URL, and model name against the provider requirements
  • Network access from the actual Chat2DB process or container
  • Whether a proxy applies to Java or Docker, rather than only to a browser
  • Provider context, rate, and credit limits
  • The first provider error recorded in the Chat2DB logs

Remove API keys, tokens, private addresses, and business data before sharing logs.

A page or feature behaves incorrectly

Do not apply procedures written for the old Electron client, removed source directories, or old ports. First record:

  • Current version and installation source
  • Community, Pro, or Enterprise
  • Desktop, Docker, Web, or source-development mode
  • The first concrete error in the browser console or Chat2DB logs

Report the problem

Choose the correct channel:

A useful bug report includes:

  • Chat2DB version and edition
  • Desktop, Docker, Web, or source runtime
  • Operating system, database type, and database version
  • Reproduction steps, expected result, and actual result
  • Sanitized logs, screenshots, or recordings

Never post passwords, tokens, API keys, private hostnames, customer data, or complete production SQL.

Chat2DB Wiki

Community

Help

Project

Clone this wiki locally