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:port. |
Transport selection issues
Symptom: Unexpected transport used, or auto-detection fails. SetMUBIT_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 v0.4.1+ which includes the keepCase fix.
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 | Increase max_token_budget (default may be 300). |
| 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 listActivity. |
Lessons not appearing after reflect
| Cause | Fix |
|---|---|
| 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_idscopes its own data. - Linked runs (
linkRun) share data intentionally. Check if runs are linked. - Use
listRuns()to see active runs and their relationships.
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
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_KEYis setMUBIT_ENDPOINTpoints 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