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.

​
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.

​
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.