> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot HelixDB

> Diagnose query, index, vector, embedded, and local runtime failures

<div className="flex flex-wrap gap-2"><Badge color="orange" size="sm">Troubleshooting</Badge></div>

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](/database/helix-cloud/operate/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](/database/helix-db/start-here/local-development/embedded-database#install).

## 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](/database/helix-cloud/operate/limits#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](https://status.helix-db.com) 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](/database/helix-db/start-here/local-development/local-server).

## 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](mailto:founders@helix-db.com).