Error Code Reference

This document provides a comprehensive list of all ReasonKit error codes, their meanings, and how to resolve them.

1. Engine Errors (RK-1xxx)

Errors generated by the core Rust execution engine.

RK-1001: `ProtocolNotFound`

Cause: The requested ThinkTool protocol file (.yaml or .toml) was not found in the search path.
Solution: Check your REASONKIT_PROTOCOLS_PATH environment variable. Run rk tools list to see all available tools.

RK-1002: `InvalidSchema`

Cause: The protocol file violates the ThinkTool Specification.
Solution: Run rk validate <file> to identify the specific field that is malformed.

RK-1003: `CircularDependency`

Cause: A composite ThinkTool is calling itself or creating an infinite loop.
Solution: Inspect your thinking_pattern.steps and ensure there are no recursive cycles.

RK-1004: `StepTimeout`

Cause: A reasoning step took longer than the configured limit (default 30s).
Solution: Increase the timeout in your profile or switch to a faster model.

2. Provider Errors (RK-2xxx)

Errors returned by external LLM providers (Anthropic, OpenAI, etc.).

RK-2001: `AuthenticationFailed`

Cause: Invalid or expired API key.
Solution: Verify your ANTHROPIC_API_KEY or OPENAI_API_KEY.

RK-2002: `RateLimitExceeded`

Cause: Too many requests to the model provider.
Solution: Implement exponential backoff or upgrade your provider tier. ReasonKit MCP (Pro) automatically handles queuing for enterprise tenants.

RK-2003: `ContextWindowExceeded`

Cause: The prompt + reasoning trace is too large for the model’s window.
Solution: Use a quick profile or reduce the number of parallel steps in your protocol.

RK-2004: `ProviderDown`

Cause: The upstream API is unreachable.
Solution: Check the status page of your provider. ReasonKit will automatically attempt failover if configured.

3. Data & Storage Errors (RK-3xxx)

Errors related to RAG, Vector DBs, and caching.

RK-3001: `VectorStoreUnavailable`

Cause: Cannot connect to Qdrant or Tantivy index.
Solution: Ensure your database container is running and accessible via the URL in rk.toml.

RK-3002: `RedactionFailure`

Cause: PII stripping middleware encountered an error during regex processing.
Solution: Check the logs for malformed input strings. Ensure your PII rules are valid regex.

4. Getting Debug Logs

If you encounter an error not listed here, run the CLI with verbose output:

rk think "..." --verbose

This will output the full Rust backtrace and internal state of the reasoning engine.