Troubleshooting

The gRPC examples require the downloadable API definitions and SHRIKEDB_API_DIR setup. This page starts with common user-facing problems.

Server Will Not Start

Symptom Likely cause Try

Port already in use

Another ShrikeDB process or service is bound to the port.

Change grpc_bind, http_bind, or admin_bind; or stop the other process.

Permission denied on data directory

The binary/container cannot write to storage.data_dir.

Create the directory and fix ownership, or mount a writable volume.

Config not found

--config or SHRIKEDB_CONFIG points to the wrong path.

Use an absolute path and check Configuration.

Container starts then exits

Entrypoint, config, or data-dir mount mismatch.

Run docker logs shrikedb and verify volume paths.

Health Is Not Ready

curl http://127.0.0.1:9190/health/live
curl http://127.0.0.1:9190/health/startup
curl http://127.0.0.1:9190/health/ready

If liveness passes but readiness fails, the process is up but not ready for traffic. Check logs and storage recovery messages.

gRPC Calls Fail

Error Likely cause Fix

connection refused

Wrong port, server down, or container port not published.

Use 50251 for gRPC and include -p 50251:50251 for Docker.

unknown service

Calling the HTTP/admin port or wrong service name.

Use shrikedb.v2.ShrikeDbService.

invalid JSON

Protobuf JSON field names or bytes are wrong.

Use lowerCamelCase fields and base64 for bytes.

unauthenticated

Multi-tenant auth is enabled.

Pass authorization: Bearer …​ or x-shrikedb-api-key.

Query Returns No Rows

Check in this order:

  1. Did you load data?

  2. Are you querying the same UID, schema ID, resource ID, or index name you wrote?

  3. For vector search, does the query vector have the same dimension as the index?

  4. For graph queries, did the graph projection catch up?

  5. For multimodal queries, does each modality use the same UID?

Useful checks:

curl http://127.0.0.1:8182/api/v1/admin/kv/namespaces
curl http://127.0.0.1:8182/api/v1/admin/vector/namespaces
curl http://127.0.0.1:8182/api/v1/admin/multimodal/alignment

Vector Search Looks Wrong

Common causes:

  • mixed dimensions inside one index,

  • wrong index name,

  • too-small k,

  • too-small efSearch,

  • filters that exclude all candidates,

  • embeddings from different models in the same index.

Try:

grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -d '{
    "indexName":"your_index",
    "queryVector":[0.1,0.2,0.3],
    "k":10,
    "efSearch":200
  }' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/VectorSearchPacked

Cypher Parse Or Plan Errors

ShrikeDB supports practical Cypher shapes, not every Cypher feature. Check Feature Status before assuming a syntax form is available.

Current safe shapes include:

  • MATCH / WHERE / RETURN,

  • ORDER BY / SKIP / LIMIT,

  • CALL vector.knn(…​) YIELD …​,

  • CALL kv.get(…​) YIELD …​,

  • SEARCH …​ AS …​,

  • RANK rerank_v3(…​),

  • scoped MERGE …​ SET …​ RETURN node upsert.

Where To Look Next