Help

Troubleshooting

Common issues, error messages, and solutions for MuBit SDK and API usage.

Authentication

Invalid API key

Symptom: 401 Unauthorized or UNAUTHENTICATED gRPC error.

Causes and fixes:

Cause	Fix
Malformed key	API keys follow the format `mbt_<instance>_<key_id>_<secret>`. Verify all four segments are present.
Wrong instance	The instance tag in the key must match the endpoint's instance. Check your `MUBIT_API_KEY`.
Revoked key	Keys can be revoked via `revokeUserApiKey`. Generate a new key with `rotateUserApiKey`.
Missing env var	Ensure `MUBIT_API_KEY` is set in your environment or passed to the SDK constructor.

Transport and connectivity

Connection refused

Symptom: ECONNREFUSED or Connection refused.

Context	Fix
Local development	Ensure MuBit is running (`make run-mubit`). Default ports: HTTP 3000, gRPC 50051.
Hosted endpoint	Check network connectivity to `api.mubit.ai`. Verify no firewall blocking HTTPS/443.
gRPC transport	Verify `MUBIT_GRPC_ENDPOINT` points to the correct host .

Transport selection issues

Symptom: Unexpected transport used, or auto-detection fails.

Set MUBIT_TRANSPORT explicitly to "http" or "grpc" instead of relying on "auto". The auto probe can fail in restricted network environments.

gRPC field names wrong (JS SDK)

Symptom: Response fields use camelCase instead of snake_case proto names, or vice versa.

Fix: Update @mubit-ai/sdk to the latest version. Current SDKs decode proto responses with keepCase: false by default, so fields surface as camelCase.

Memory and retrieval

Recall returns empty results

Cause	Fix
Data not yet ingested	Ingest is async. Wait for the ingest job to complete (poll `getIngestJob`).
Wrong `run_id`	`recall` scopes by `run_id`. Ensure you're querying the same run.
Entry types filter too narrow	Broaden `entry_types` or omit it to search all types.
Lane mismatch	If using lanes, ensure `lane_filter` matches the `lane` used at ingest time.

Context block is empty or too small

Cause	Fix
Token budget too low	The default `max_token_budget` is 0, which means no cap. If you set a small budget, raise it; 0 imposes no limit.
No relevant evidence	Ingest more data or broaden the query.
Wrong mode	Try different `mode` values: `"summary"`, `"full"`, `"compact"`.
Run has no data	Verify the `run_id` has ingested data with `getRunIngestStats` / `getIngestJob`, or query the activity log directly via `POST /v2/control/activity`.

Lessons not appearing after reflect

Cause	Fix
Lesson is still a pending candidate	Reflected lessons are gated: they enter as `pending` and are promoted to `active` once their validation score crosses the accept threshold (default 0.6). Record outcomes against the lesson to accrue evidence, or disable the gate with `MUBIT_CONTROL_LESSON_VALIDATION_ENABLED=0`.
No outcomes recorded	Pair `reflect()` with `recordOutcome()` for stronger lesson extraction.
Too few data points	Reflection needs sufficient evidence. Ingest more interactions before reflecting.
Step outcomes not included	Pass `include_step_outcomes=True` to include step-level signals.

Runs and scoping

Run scope conflicts

Symptom: Data from one run appears in another, or data is missing.

Runs are the primary isolation boundary. Each run_id scopes its own data.
Linked runs (linkRun) share data intentionally. Check if runs are linked.
Inspect active runs and their relationships with client.control.listRunHistory(...) (JS) / client.advanced.list_run_history(...) (Python), or GET /v2/control/runs.

Cannot delete a run

Symptom: deleteRun fails or data persists.

Run deletion is permanent and removes all associated data.
Ensure no active ingest jobs are running for the run.
Both control and core planes have deleteRun — the control version handles both.

Lesson promotion

How lesson promotion works

Lessons are promoted through scopes based on recurrence:

Run-scoped — extracted from a single run's evidence
Session-scoped — promoted when the same lesson appears across multiple runs
Global — promoted when recurring across sessions

Promotion happens automatically during reflect(). You can inspect lesson scope with listLessons().

Integration packages

Framework adapter not connecting

All integration packages (mubit-crewai, mubit-langgraph, etc.) use the core SDK internally. Verify:

MUBIT_API_KEY is set
MUBIT_ENDPOINT points to a reachable MuBit instance
The adapter package version matches your SDK version

Getting help

SDK issues: github.com/mubit-ai/ricedb/issues
API reference: Control HTTP | Control gRPC
Configuration: SDK Configuration Reference