Troubleshooting

A query failure is identified by its status, info, and failing command. The response reference defines status codes and error envelopes. Remove passwords, full tokens, credential keys, and private object URLs before sharing logs.

Query and response failures

Symptom	Check	Recovery
returned: 0 from a successful Find	Did the command only declare _ref, or request an aggregate?	Ask for results: {"count": true} or a property list. Omitted payloads do not prove zero matches.
Status 1 after AddConnection	Did both endpoint lookups match objects?	Correct the source/destination searches; no connection was created.
Status 3	Did a unique: true search match more than one object, or did another count expectation fail?	Inspect info, narrow the filter, or remove an unnecessary uniqueness requirement.
Status 5	Does the write conflict with an existing property's type?	Inspect GetSchema, then correct the property type or model.
Status 4 or “Response size is too large”	Does the response include large images, videos, vectors, or blobs?	Reduce limit, request fewer properties, resize returned media, or set blobs: false.
Invalid reference	Is the reference declared by an earlier command in this same query?	Use _ref to declare a selection and ref to use it. References do not survive the query.
Credential or remote fetch error	Does the credential authorize this exact bucket/origin? Is the URL directly accessible within its limits?	Check credential syntax, certificate, origin, object size, and timeout. A generic HTTPS error does not identify a single cause.

Errors can appear at the top level or inside individual command results. An array response can contain a failed command, so its presence alone does not indicate success.

Graph metadata operations are transactional, but response construction and transport follow that transaction. A connection or response-size error can occur after a write has committed. Check persisted objects or administrative state before retrying a query that writes data; use application identifiers and conditional adds to prevent duplicates.

Message size limits

The database's native message budget defaults to 256 MiB. The server JSON key is max_connection_message_size_mb, with environment override ADB_MAX_CONNECTION_MESSAGE_SIZE_MB; its integer unit is MiB and zero selects the default. An oversized incoming native message can fail before producing a JSON response. An outgoing failure can return status 4.

HTTP proxy request-body limits are separate and can reject a request before it reaches the database. Raising a proxy body limit does not raise the native response budget. Check the configuration reference and your deployment package's proxy settings. Pagination or smaller media results usually resolve an oversized response without raising memory limits.

TLS connection errors

The SDK enables TLS and certificate verification by default. Verify the host, port, certificate expiry, hostname, and issuing CA first. For a private CA, configure ca_cert with the trusted CA certificate; keep hostname verification enabled. Ensure the chosen endpoint is the native database listener or the HTTP gateway expected by your client.

verify_hostname=False disables certificate verification as well as the hostname check in the Python connector. use_ssl=False sends unencrypted traffic and requires a server that permits it, such as ADB_FORCE_SSL=false. Use those settings only for an explicitly isolated local evaluation. The deployment guide explains which service terminates TLS; the database's force_ssl and Lenz's LNZ_FORCE_SSL govern different processes.

Upgrade failures

Before replacing images, check the database compatibility requirements and the selected package's deployment instructions. Keep a verified backup and validate application reads and writes after the update.

Clients that parse GetSchema read property objects containing count and type. GetIndexes returns index definitions separately. The release notes document changes to these responses.

Ask for help

Send a minimal query, sanitized status/info, client/server versions, connection method, and steps to reproduce to team@aperturedata.io, or use your team's support channel. State whether writes may already have committed and what checks you performed before retrying.