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

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

## 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).