Skip to content

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.

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.

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.

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 admin password
  • 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.

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.

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.

Cause: data plus compaction headroom outgrew the instance’s storage.

Fix: compact (POST /<db>/_compact) or grow storage. See Resize.

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.

Neither is available: instances are single-node Community Edition. Backups are crash-consistent copies of the data directory, with no point-in-time recovery.

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.