Troubleshooting

Common issues and how to fix them.

Missing authorization

Symptom: 401 Unauthorized.

Fix: Include the Bearer token in every request:

-H "Authorization: Bearer $DEEPLAKE_API_KEY"

Embedding dtype drift

Symptom: Insert fails or search returns bad results.

Cause: Embeddings stored as float16 or bfloat16 instead of float32.

Fix: Always convert to float32 before building the SQL literal:

# PyTorch
embedding = model_output.to(torch.float32).cpu().tolist()

# NumPy
embedding = model_output.astype("float32").tolist()

SQL parse error on INSERT with embeddings

Cause: Nested arrays have inconsistent dimensions, or contain None values.

Fix: Validate before building the literal:

# Single vector: all elements must be floats
assert all(isinstance(v, (int, float)) for v in embedding)

# Multi-vector: all rows must have the same length
assert len(set(len(row) for row in multi_embedding)) == 1

Rate limiting (429)

Symptom: 429 Too Many Requests.

Fix: Retry with exponential backoff. Retryable status codes: 429, 502, 503, 504.

MAX_RETRIES=3
ATTEMPT=0
while [ $ATTEMPT -lt $MAX_RETRIES ]; do
  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
    "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
    -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
    -d '{"query": "SELECT 1"}')

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)

  if [ "$HTTP_CODE" = "429" ]; then
    SLEEP_TIME=$((2 ** ATTEMPT))
    echo "Rate limited. Retrying in ${SLEEP_TIME}s..."
    sleep $SLEEP_TIME
    ATTEMPT=$((ATTEMPT + 1))
  else
    echo "$RESPONSE" | head -n -1
    break
  fi
done

BM25 sort order

Symptom: BM25 search returns irrelevant results first.

Cause: All <#> operator searches (vector, BM25, and hybrid) use DESC ordering - higher score = more relevant.

Fix:

Search mode	Sort order
Vector	ORDER BY score DESC
BM25	ORDER BY score DESC
Hybrid	ORDER BY score DESC

Table not found

Symptom: relation "my_table" does not exist.

Cause: Table name is not schema-qualified with the workspace name.

Fix: Always schema-qualify:

SELECT * FROM "my_workspace"."my_table"    -- correct
SELECT * FROM "my_table"                    -- wrong
SELECT * FROM my_table                      -- wrong

In curl:

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT * FROM \"'"$DEEPLAKE_WORKSPACE"'\".\"'"$TABLE"'\""
  }'

Eventual consistency after INSERT

Symptom: SELECT returns no rows (or fewer rows than expected) immediately after INSERT.

Cause: Deeplake tables have eventual consistency. After an INSERT, data typically takes 2-3 seconds to become visible in SELECT queries.

Fix: If you need to query immediately after inserting, add a short delay:

# Insert data
curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "INSERT INTO \"'"$DEEPLAKE_WORKSPACE"'\".\"'"$TABLE"'\" (title) VALUES ($1)",
    "params": ["My doc"]
  }'

sleep 3  # Wait for consistency

# Now query
curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT * FROM \"'"$DEEPLAKE_WORKSPACE"'\".\"'"$TABLE"'\""
  }'

This is normal behavior, not an error. In production workflows where you insert and query separately, this is typically not an issue.

Missing USING deeplake on table

Symptom: Index creation fails, or search operators (<#>) return errors.

Cause: The table was created without USING deeplake.

Fix: Recreate the table with the USING deeplake engine clause:

CREATE TABLE "my_workspace"."my_table" (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding FLOAT4[]
) USING deeplake;

Empty search results

Symptom: Search returns no rows.

Checklist:

1. Was the table created with USING deeplake? This is required for indexes to work.
2. Are table names schema-qualified? Use "workspace"."table", not just "table".
3. Are there rows? SELECT COUNT(*) FROM "my_workspace"."my_table"
4. Did you wait for eventual consistency? (typically 2-3 seconds after INSERT)
5. Do embeddings exist? SELECT COUNT(*) FROM "my_workspace"."my_table" WHERE embedding IS NOT NULL
6. Is the index created? CREATE INDEX IF NOT EXISTS ...
7. Are dimensions correct? Query embedding must match stored embedding dimensions.