Skip to main content
Troubleshooting
Start with the first error returned by the SDK or server. HelixDB rejects invalid requests and transactions instead of partially applying them. For the stable Cloud response envelope and gateway code reference, see Error handling.

​
Request uses the wrong AST shape

Symptoms: unknown variant errors, missing query, or a request containing top-level step arrays. Fix:
  1. Prefer a current SDK builder.
  2. Confirm the request uses request_type, query_name, and a query.read or query.write batch.
  3. Confirm every nested operation uses root or input and snake_case wire tags.

​
Response is missing expected data

Only names listed in returns are present in the response. Confirm the traversal was assigned with varAs or var_as, then add that name to returning. If a ranked field such as $distance is needed after another traversal, project it before leaving the hit stream.

​
Index operation is blocked

Poll the receipt’s operation_id and inspect blocker_code. Correct the source data or coordination issue, then retry the same operation. Abort a constructing build when you want cleanup instead of activation. Do not create repeated definitions to work around a blocker: existing_operation deliberately points callers at the durable in-flight operation.

​
Vector dimension mismatch

The stored vector and query vector must have exactly the dimension declared by the index. Check all three values:
  • Index definition dimension
  • Existing property arrays included by the backfill
  • Runtime query vector
Malformed existing values block index activation; malformed query vectors fail the request.

​
Embedded runtime is unavailable

An EmbeddedUnavailable error means the embedded runtime package could not load for the current environment. Reinstall the matching package or switch to Client.server(...). Review the embedded installation guide.

​
Embedded reader rejects a request

A reader handle is read-only. Open a writer handle for mutations. Server-only request options are also rejected in embedded mode because no routing gateway is present.

​
Request returns HTTP 409

A conflict means the request could not commit against current transactional state. Retry the entire idempotent transaction with bounded backoff. Do not retry only part of a multi-mutation request. For non-idempotent business actions, attach an application-level idempotency key or read the latest state before deciding whether to resubmit.

​
Request returns HTTP 429

rate_limited means the shared request bucket for the Cloud database has no token available. The rejected query did not reach database execution. Wait for the response’s Retry-After interval before retrying. Add jitter when many workers can wake together, and inspect aggregate traffic across every API key and application instance that uses the database. All of them share the same bucket. See Helix Cloud request rate limits for the current plan limits and token-bucket behavior.

​
Request returns rate_limit_unavailable

An HTTP 503 with rate_limit_unavailable means the gateway could not make a safe distributed admission decision. It fails closed, so the query did not reach database execution. Retry with bounded exponential backoff and jitter. If the response persists, check HelixDB status and include the response code, timestamp, and database identifier when contacting support.

​
Local server cannot reach storage

For S3-compatible local storage:
  1. Confirm the container can resolve the configured endpoint.
  2. Confirm bucket, region, credentials, and HTTP allowance match the service.
  3. Use the service name visible inside the container network, not a host-only alias.
  4. Restart the local instance after changing storage environment variables.
See local development.

​
Still blocked?

Capture the SDK version, request JSON with secrets removed, complete error, operation ID for lifecycle failures, and deployment mode. Include them when contacting founders@helix-db.com.