Troubleshoot a workflow

Start with the smallest action that fails. Record the selected source and the original error, then change one relevant input at a time. This makes it possible to tell which change resolved the problem.

Cannot connect#

Check the source type, hostname, port, database name, credentials, and required TLS settings. The connection originates from the WhoDB backend, so test reachability from its machine or container.

Inside Docker, localhost means the container itself. A database elsewhere needs a reachable hostname. For SQLite or DuckDB, check the path and file permissions from the WhoDB process and use the mounted container path.

A timeout points to reachability. An authentication error indicates that the database rejected the supplied identity. Use the original message to decide which to investigate.

Login returns to the connection page#

Check server logs and whether the browser accepts the session cookie. For an HTTPS deployment, including one behind a TLS-terminating proxy, set WHODB_SECURE=true. Leave it unset for plain HTTP development.

If sessions stop working after container replacement, check that the data directory and encryption key were preserved. See Session storage.

Expected objects or actions are missing#

Verify the active database and schema, then check the account's database permissions. An account may be allowed to connect without being able to inspect every object.

Check Supported databases for source-specific operations. Missing unsupported actions are different from a supported action returning an error.

Data or queries look wrong#

Clear filters, return to the first page, and run again. Remember that Search only checks loaded rows. For a Scratchpad failure, inspect names and syntax, then reduce the query to a small read before adding joins or aggregates back.

For an import, read the preview and validation error before resubmitting. Check headers, types, generated fields, and mode. If a write's outcome is uncertain, inspect the source before retrying.

Chat cannot answer#

Confirm that a provider and model are selected. Check credentials, endpoint, model identifier, and backend reachability. If generation succeeds but execution fails, inspect the generated query and selected schema. See AI setup.

Report the failure#

Include the WhoDB version, source type, steps, expected result, and redacted logs. For a CLI connection, use whodb doctor --connection <name> --format json for diagnostics. Remove passwords, tokens, private keys, and sensitive records before sharing evidence.

Common errors maps visible symptoms to checks. Performance tuning covers operations that succeed slowly.