Troubleshooting & FAQ

Actionable Error Hints

Since v2026.4.12, the CLI shows contextual fix suggestions alongside errors instead of raw tracebacks.

YAML validation errors now include human-readable hints:

Error in role.yaml (line 12, col 5):
  spec.guardrails.max_tokens_per_run — expected an integer; check for missing quotes or a stray number

Run flag conflicts name the specific flags involved:

Error: --confirm-role requires --sense.
  It confirms the auto-selected role before running.

Error: --api-key only applies to --serve mode.

Deprecation auto-fix patches stale YAML fields in-place while preserving formatting. Run initrunner doctor --fix to scan and repair, or --fix --yes for CI:

initrunner doctor --fix --role role.yaml

Fixed
  Installed initrunner[anthropic]
  Bumped spec_version to 2

Provider & API Key Issues

API key not found

Error: API key not found for provider 'openai'

InitRunner looks for API keys in this order:

spec.model.api_key in the role file (not recommended for production)
Environment variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc.
.env file in the role file's directory
~/.initrunner/.env global config

Fix: Export the key or add it to your .env file:

export OPENAI_API_KEY=sk-...

Or, to persist across sessions, add it to ~/.initrunner/.env:

OPENAI_API_KEY=sk-...

Since v2026.4.10, interactive terminals get a faster path: initrunner run detects the missing key, prompts for it inline, and writes it to ~/.initrunner/.env (mode 0600) so the same command continues without a restart. No initrunner setup round-trip needed. Non-interactive sessions (CI, piped stdin, redirected stdout) keep the fail-fast error above so scripted callers still exit with code 1.

Model not found

Error: Model 'gpt-5-turbo' not found for provider 'openai'

Fix: Check the model name matches your provider's available models. Run:

initrunner models --provider openai

See Providers for supported models per provider.

Rate limiting / 429 errors

Error: Rate limit exceeded (429)

Fix:

Reduce max_tokens_per_run or max_tokens to limit output length per call
Add iteration_delay_seconds in autonomous mode to space out requests
Switch to a higher-tier API plan
Use a different model (e.g., gpt-4o-mini instead of gpt-4o)

Chat & Bot Mode

No API key found (ephemeral mode)

Error: No API key found. Run initrunner setup or set an API key environment variable.

No provider was detected. Either export an API key or start Ollama locally:

export ANTHROPIC_API_KEY="sk-..."
# or
ollama serve

You can also add the key to ~/.initrunner/.env so it persists across sessions.

Unknown tool profile

Error: Unknown tool profile 'foo'. Use: none, minimal, all

The --tool-profile value must be one of none, minimal, or all.

Unknown tool type

Error: Unknown tool type 'foo'.
  Supported: datetime, filesystem, git, python, search, shell, slack, web_reader

The --tools value must be one of the supported extra tool types. Run initrunner run --list-tools to see the full list.

Missing required environment variable for tool

Error: Tool 'slack' requires SLACK_WEBHOOK_URL.
  Export it or add it to your .env file:
  export SLACK_WEBHOOK_URL=your-value

Some tools require environment variables. Set the variable before running the command.

--telegram and --discord are mutually exclusive

Error: --telegram and --discord are mutually exclusive.

You can only launch one bot platform at a time. To run both, use two separate role files with initrunner run --daemon.

TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN not set

Error: TELEGRAM_BOT_TOKEN not set. Export it or add it to your .env file:
  export TELEGRAM_BOT_TOKEN=your-bot-token

Export the token or add it to ~/.initrunner/.env:

TELEGRAM_BOT_TOKEN=your-token-here

Module not found (telegram / discord)

Error: python-telegram-bot is not installed.
  Install it: uv pip install initrunner[telegram]

Install the platform's optional dependency:

uv pip install "initrunner[telegram]"
# or
uv pip install "initrunner[discord]"

Wrong provider auto-detected

Auto-detection uses a priority order (see CLI Reference — Provider Auto-Detection). If you have multiple API keys set and the wrong provider is picked, override explicitly:

initrunner run --provider anthropic

Tool Execution Failures

Tool not found

Error: Tool 'search_documents' is not registered

Fix: This usually means the tool wasn't configured in spec.tools, or for search_documents, you haven't added an spec.ingest section. Run initrunner ingest role.yaml after adding ingestion config.

Permission denied (filesystem)

Error: Access denied: path '/etc/passwd' is outside allowed root

Filesystem tools are sandboxed to root_path. You cannot access files outside the configured directory.

Fix: Update root_path in your filesystem tool config, or use an absolute path that falls within the allowed root.

Shell command blocked

Error: Command 'rm' is not in the allowed commands list

Shell tools restrict which commands can run via allowed_commands.

Fix: Add the command to the allowlist in your role file:

tools:
  - type: shell
    allowed_commands:
      - curl
      - rm  # add the command you need

MCP connection failed

Error: Failed to connect to MCP server at localhost:3001

Fix:

Verify the MCP server is running and listening on the expected port
Check that the url in your MCP tool config matches the server address
Test connectivity: curl http://localhost:3001/health

Memory & Ingestion Problems

No documents ingested

search_documents returned: "No documents have been ingested yet"

Fix: Run the ingestion pipeline before querying:

initrunner ingest role.yaml

Make sure your spec.ingest.sources glob patterns match actual files:

# Test the glob pattern
ls docs/**/*.md

Memory not persisting between sessions

Session history (short-term) only lasts for the duration of a single session or daemon run. To recall facts across sessions, enable semantic memory:

spec:
  memory:
    semantic:
      max_memories: 1000

Note: Short-term session history is separate — use --resume to reload it. The remember() and recall() tools operate on the semantic memory store above.

See Memory for the full schema and all memory types (semantic, episodic, procedural).

Embedding errors

Error: Failed to generate embeddings

Fix:

Check that the embedding provider API key is set
Verify the embedding model exists (e.g., text-embedding-3-small for OpenAI)
If using a different provider for embeddings than for the main model, set ingest.embeddings.provider explicitly

YAML Configuration Mistakes

Missing required fields

Error: 'spec.role' is required

Every role file needs at minimum:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: my-agent
spec:
  role: Your system prompt here.
  model:
    provider: openai
    name: gpt-4o-mini

Indentation errors

YAML is indentation-sensitive. Use 2 spaces (not tabs). Common mistakes:

# Wrong — tools is not under spec
spec:
  role: ...
tools:          # should be indented under spec
  - type: shell

# Correct
spec:
  role: ...
  tools:
    - type: shell

Environment variable substitution

Variables like ${SLACK_WEBHOOK_URL} are resolved at runtime from the environment. If they resolve to empty strings:

Fix:

Export the variable: export SLACK_WEBHOOK_URL=https://hooks.slack.com/...
Add it to .env in the role file's directory
For systemd/flow deployments, use the environment file (see Flow)

Autonomous Mode Issues

Infinite loops / agent won't stop

Cause: The agent keeps creating new plan steps or never calls finish_task.

Fix: Set guardrails to enforce limits:

guardrails:
  max_iterations: 5
  autonomous_token_budget: 30000
  max_tool_calls: 15
autonomy:
  max_plan_steps: 6
  iteration_delay_seconds: 2

The agent will stop when any limit is reached.

Empty or vague plans

Cause: The system prompt doesn't give the agent clear enough instructions on what to do.

Fix: Be specific in spec.role about the expected workflow:

role: |
  You are a deployment checker. Follow these steps exactly:
  1. Use update_plan to create a verification checklist
  2. Run curl for each endpoint
  3. Mark each step passed or failed
  4. Call finish_task with the overall result

See Autonomy for best practices.

Token budget exceeded too quickly

Cause: The autonomous_token_budget is too small for the task complexity, or the agent is making many tool calls that produce large outputs (shell commands, HTTP responses, file reads).

Fix:

Increase autonomous_token_budget to give the agent more room
Lower model.max_tokens to reduce per-response output
Reduce max_tool_calls to limit tool invocations per iteration
Use more specific tool configs (e.g., narrower allowed_commands, smaller file reads) to reduce output volume

Scheduled follow-ups lost on daemon restart

Cause: Tasks scheduled via schedule_followup or schedule_followup_at are held in-memory only. When the daemon process stops or restarts, all pending scheduled tasks are discarded.

Fix:

Use cron triggers for predictable recurring work instead of schedule_followup
For critical follow-ups, have the agent persist the schedule externally (file, database, or message queue) and use a cron trigger to poll for pending work
If running under systemd, configure Restart=on-failure to minimize unexpected restarts

Daemon & Trigger Issues

Cron not firing

Fix:

Verify the cron expression is valid (5-field format: min hour day month weekday)
Check timezone — defaults to UTC
Make sure the daemon is running: initrunner run role.yaml --daemon
Check audit logs for errors: sqlite3 ~/.initrunner/audit.db "SELECT * FROM events ORDER BY created_at DESC LIMIT 10"

File watcher not detecting changes

Fix:

Ensure the paths directory exists before starting the daemon
Check extensions filter — an empty list watches all files, a populated list only watches those extensions
Increase debounce_seconds if events are being swallowed by rapid consecutive changes
Verify process_existing: true if you want existing files to be processed on startup

Webhook not receiving events

Fix:

Confirm the port is not already in use: ss -tlnp | grep 8080
Test locally: curl -X POST http://127.0.0.1:8080/webhook -d '{"test": true}'
If using HMAC verification (secret), ensure the sender includes a valid X-Hub-Signature-256 header
Check firewall rules if the sender is on a different host

See Triggers for full configuration.

Flow Issues

Circular dependency detected

Error: Circular dependency: a -> b -> c -> a

Fix: Redesign the agent graph so that data flows in one direction. The most common approaches are:

Remove the back-edge — identify which delegation is redundant and drop it.
Introduce an intermediary — instead of A delegating to B and B delegating back to A, have both delegate to a third agent C.

Example of a circular config and how to break it:

# Broken — a and b delegate to each other
agents:
  a:
    role: roles/a.yaml
    sink: { type: delegate, target: b }
  b:
    role: roles/b.yaml
    sink: { type: delegate, target: a }   # circular!

# Fixed — b writes to a file sink instead of delegating back
agents:
  a:
    role: roles/a.yaml
    sink: { type: delegate, target: b }
  b:
    role: roles/b.yaml
    sink: { type: file, path: output/result.txt }

If b genuinely needs to pass results back upstream, use a shared file, database, or message queue as an intermediary rather than a delegate sink.

Delegate sink not connecting

Error: Delegate target 'consumer' not found in agents

Fix: The target name in a delegate sink must exactly match an agent name defined in spec.agents. Check for typos.

Agents not starting in order

Fix: Add needs to enforce startup ordering:

agents:
  producer:
    role: roles/producer.yaml
    sink: { type: delegate, target: consumer }
  consumer:
    role: roles/consumer.yaml
    needs: [producer]

See Flow for the full orchestration guide.

Performance Tips

Choose the right model — Use gpt-4o-mini or equivalent for simple tasks. Reserve larger models for complex reasoning.
Limit guardrails to what you need — Overly aggressive max_tool_calls or max_tokens_per_run can cause agents to stop before finishing useful work.
Use read_only: true on filesystem tools when agents only need to read files. This skips confirmation prompts and reduces overhead.
Tune chunking for RAG — Smaller chunks (256-512) give more precise search results. Larger chunks (1024+) provide more context but may dilute relevance.
Use paragraph chunking for prose — It preserves document structure better than fixed chunking for documentation and articles.
Add iteration_delay_seconds in autonomous mode to avoid hitting rate limits.

Data	Default Location
Audit logs	`~/.initrunner/audit.db`
Memory	`~/.initrunner/memory/<agent-name>.lance`
Ingestion vectors	`~/.initrunner/stores/<agent-name>.lance`
Session state	In-memory (lost on exit)

How do I reset memory?

Delete the memory database file:

rm -r ~/.initrunner/memory/my-agent.lance

Or re-ingest documents to rebuild the vector store:

initrunner ingest role.yaml

Can I use InitRunner in CI/CD?

Yes. Use single-shot mode with -p to pass a prompt and capture the output:

initrunner run role.yaml -p "Analyze the latest test results" --output json

Set API keys as CI environment variables. See Testing for test automation patterns.

How do I update InitRunner?

pip install --upgrade initrunner

Or with extras:

pip install --upgrade "initrunner[ingest]"

On this page