Help
CouchDB and TypeDB errors and how to fix them
Tested with:Databasezy API v1 · zb CLI 0.1
CouchDB is available on paid plans only. TypeDB is available on every plan, including Free. Both are reached over
HTTPS on port 443 (8443 in single-IP regions), and both use a generated admin password that Databasezy manages. A
rotation restarts the instance, and the old password stops working at that restart. There is no overlap window.
Errors on both engines
Section titled “Errors on both engines”The connection closes during the TLS handshake
Section titled “The connection closes during the TLS handshake”Cause: the gateway closes the connection without a response in these cases:
- the client used
http://or turned TLS off - the client connected by IP address
- your address is not on the allow-list
- your address is temporarily blocked after repeated failed logins
Fix: use the host from the Connect tab with TLS on, and add your egress CIDR under Network → IP allow-list. See IP allow-lists.
Paused, waking up or too many connections
Section titled “Paused, waking up or too many connections”Cause: the gateway answers these itself. On HTTP, you get a JSON body with error set to paused, wake_timeout,
too_many_connections, rate_limited or suspended. Free TypeDB instances sleep after 15 minutes without
connections, and the first connection is held for up to 30 seconds while the instance wakes (wake_timeout if it is
not ready in time). paused means someone paused the instance on purpose, or support did as the message says;
connections never wake it.
Fix: retry after wake_timeout. For paused, run zb instances resume <instance_id> (support pauses need
support). See
Paused and waking instances and
Too many connections.
CouchDB
Section titled “CouchDB”401 {"error":"unauthorized","reason":"Name or password is incorrect."}
Section titled “401 {"error":"unauthorized","reason":"Name or password is incorrect."}”Cause: the password is wrong or was rotated. Another cause: someone changed the admin password through CouchDB’s
configuration API. That change lasts only until the next restart, when the generated password applies again.
Fix: reveal the current password with zb instances credentials reveal <instance_id>. Rotate it from the portal or
API, not inside CouchDB. For applications, create users in _users and grant them access through each database’s
_security object. Those users are not affected by rotation. See CouchDB.
PouchDB in the browser fails with a CORS error
Section titled “PouchDB in the browser fails with a CORS error”Cause: CORS is off by default.
Fix: turn it on for your origin through the configuration API: set [chttpd] enable_cors to true and
[cors] origins to your site. The setting persists across restarts.
A setting I changed went back after a restart
Section titled “A setting I changed went back after a restart”Cause: the platform resets a few settings at every start:
- the
adminpassword - the HTTP port and bind address
- the data directories
Other settings persist.
Fix: use the portal or API for the password. The other platform settings cannot be changed.
413 or document_too_large
Section titled “413 or document_too_large”Cause: CouchDB limits documents to 8 MB by default (max_document_size), and request bodies by
max_http_request_size.
Fix: keep attachments small. Store large files in object storage and keep a link in the document.
Replications or _changes feeds stop
Section titled “Replications or _changes feeds stop”Cause: pausing or restarting the instance closes live replications and feeds. Each feed also holds one connection.
Fix: use retry: true in PouchDB, or restart continuous replications after the instance resumes.
Writes fail because the disk is full
Section titled “Writes fail because the disk is full”Cause: data plus compaction headroom outgrew the instance’s storage.
Fix: compact (POST /<db>/_compact) or grow storage. See Resize.
TypeDB
Section titled “TypeDB”The driver or Console cannot connect, or reports a protocol error
Section titled “The driver or Console cannot connect, or reports a protocol error”Cause: the server needs a driver or Console version 3.11 or newer. TypeDB 2.x drivers never connect to a 3.x server. TLS might also be off in the driver options.
Fix: upgrade the driver and turn TLS on. Use an address (host:443), not a URL. No CA path is needed.
Authentication fails after a restart, but worked before
Section titled “Authentication fails after a restart, but worked before”Cause: someone changed the admin password inside TypeDB (with user update-password or the HTTP API). Databasezy
sets the generated password again at every restart, including pause and resume, resize and rotation.
Fix: use the revealed password for admin, and create your own TypeDB users for applications. Their passwords are
never reset.
The HTTP API or the TypeScript driver cannot connect
Section titled “The HTTP API or the TypeScript driver cannot connect”Cause: the HTTP API is on its own host name, ending in -http, not on the gRPC address.
Fix: point HTTP clients at the instance host with -http added to its first label, for example
typedb-<id>-http.<region>.databasezy.com, on the same port.
Queries slow down, or the instance restarts as data grows
Section titled “Queries slow down, or the instance restarts as data grows”Cause: TypeDB keeps much of its working set in memory. The Free size has 512 MiB.
Fix: start on a size with at least 2 GiB for real datasets. See Resize.
No cluster, and no cross-database queries
Section titled “No cluster, and no cross-database queries”Neither is available: instances are single-node Community Edition. Backups are crash-consistent copies of the data directory, with no point-in-time recovery.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket) and include:
- the instance id, engine and region
- the exact error text, or the HTTP status and body
- your driver, Console or PouchDB version
- the time of the failure in UTC
Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.