Understand common failures
Start with the original error and the action that produced it. A connection timeout, rejected password, and invalid query need different fixes even if each leaves you without a result.
| Symptom | What it usually means | Next check |
|---|---|---|
| Connection refused or timed out | The endpoint cannot be reached or is not accepting the connection | Check the host, port, database process, and firewall from the WhoDB server |
| Authentication rejected | The source rejected the supplied identity or authentication method | Check the username, password, and source-specific requirements |
| Certificate verification failed | TLS verification could not establish trust | Check the CA, server name, certificate paths, and required TLS mode |
| Expected object missing | The context or account visibility differs from what you expected | Check the database, schema, identifier, and account permissions |
| Permission denied on a query | The connected account lacks a required database privilege | Check the grants for the operation rather than changing the query to bypass them |
| Constraint or invalid-value error | The submitted record violates the field or relationship rules | Check types, required values, unique keys, and referenced records |
| Empty grid | No records matched, or the current page is beyond the result | Clear filters, return to the first page, and inspect the object |
| Import rejected | The file or chosen options failed validation | Read the preview and validation message; check headers, types, and generated fields |
| Provider or model unavailable | The backend cannot use the selected model configuration | Check the endpoint, credentials, model identifier, and reachability |
| Protected query rejected | The query is outside the selected permission mode's accepted read operations | Review MCP permissions and the exact query |
When a write's outcome is uncertain#
If a write times out or the connection drops, inspect the database before retrying. The server may have applied the change even though the client did not receive its response. Check the affected identifiers and current values before deciding whether to retry.
For an assistant operation, review the pending request and approval state as well. Approval for an earlier request is not a general permission to replay a write.
Ask for help with enough context#
Include the WhoDB version, source type, steps, expected result, and redacted error. A minimal query and small example schema are more useful than a screenshot of a generic failure notification. Remove credentials and sensitive record values.
Use Troubleshooting for a step-by-step diagnosis, or Performance tuning for an operation that succeeds slowly.
Was this page helpful?