Troubleshooting & FAQ

Start here

initrunner doctor checks providers, API keys, extras, and connectivity. See Doctor.
Turn up the logs when doctor passes but a real run still fails. initrunner -v run role.yaml -p "ping" shows provider HTTP traffic, and INITRUNNER_LOG_LEVEL=DEBUG does the same for servers and daemons where you cannot edit the command line. See Logging.

Since v2026.8.8, a failed run always logs one WARNING, in every mode, so a server no longer fails silently:

[agent.run] run 01b147e59c75 of agent 'support-bot' failed [auth]: Model API error: status_code: 401, ...

The tag in brackets after failed is the error category (auth, rate_limit, timeout, connection, server_error, usage_limit, content_blocked, unknown), which tells you what kind of problem you have before you read the message.

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):
  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: --host, --port only applies to --serve mode.

Since v2026.8.11, a flag that a target cannot use is an error rather than being silently dropped:

Error: --report, --model not supported for Team targets.

A removed flag points at what replaced it, for this release only:

Error: --api-key was removed from 'initrunner run'; use the INITRUNNER_API_KEY environment variable.

The full mapping is in CLI Reference. If you get Click's bare No such option instead of this line, you are on v2026.8.11; v2026.8.12 fixed the pointer, which only worked against the development lockfile.

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

Missing Extras

`'lancedb' is required` / `'fastmcp' is required`

Since v2026.8.9, MCP and the vector store are extras rather than core dependencies. A role that uses type: mcp, memory:, ingest:, or the web_scraper tool still validates on a core install, so initrunner validate passes and the dashboard, editors, and wizards behave normally. It fails when the agent is built, and the message carries the fix:

Error: 'lancedb' is required: uv pip install initrunner[vector]

Three ways out, in order of how much you want back:

initrunner doctor --fix --role role.yaml     # installs exactly what this role needs
uv pip install "initrunner[mcp,vector]"      # both extras
uv tool install --force "initrunner[recommended]"   # the default bundle

The same applies to Docker: the :slim tag is a core install, :latest has everything. The MCP Hub in the dashboard answers 501 with the install line for anything that needs to connect to a server. See Installation.

Ephemeral mode asks for the vector extra

Ephemeral mode turns persistent memory on by default, so a bare initrunner run needs the vector store even though you never wrote a memory: block. On a core install or the :slim image it stops at load:

Error: 'lancedb' is required: uv pip install initrunner[vector]
Hint: Persistent memory is what needs it. Add --no-memory to run without it.

Install the extra, or take the flag it names:

initrunner run -p "hi" --no-memory

The flag is the one to reach for inside a container, where installing a package is not on the table. --ingest needs the vector store whatever memory does, so it prints the install line without the flag hint.

Before v2026.8.10 this ended in a traceback instead of the two lines above. A role file with the same memory: block always reported it cleanly; only ephemeral mode was affected.

Anthropic models fail to build with a `TypeError`

On v2026.8.8 and earlier, installing Anthropic SDK 1.0.0 (released 2026-08-20) breaks Anthropic model construction: the SDK moved to httpx2 and rejects the httpx client InitRunner hands it. Upgrade to v2026.8.9 or later, which builds the client in the flavor each SDK accepts.

Provider & API Key Issues

API key not found

Error: API key not found for provider 'openai'

InitRunner looks for API keys in this order:

model.api_key_env in the role file, naming the environment variable to read (this overrides the provider default such as OPENAI_API_KEY; the key itself is never stored in the YAML)
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 the role diagnostics:

initrunner doctor --role role.yaml

The role diagnostics table flags a model name that is not in PydanticAI's known list and suggests the closest match.

See Providers for supported models per provider.

Silent failure on a server or daemon

If a client gets an error but the process log says nothing, you are on a version before v2026.8.8. Upgrade, or check the audit trail for the run's recorded error. From v2026.8.8 on, --serve, a2a serve, --daemon, flow, team, and dashboard runs all log the failure with its category. See Logging.

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

A profile name passed to --tools must be one of none, minimal, or all. Since v2026.8.11, --tools takes both profile names and individual tool types, and --tool-profile is gone.

Unknown tool type

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

The --tools value must be a profile name or one of the supported tool types. Run initrunner run --help for the full list; --list-tools was removed in v2026.8.11.

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 --model anthropic:claude-sonnet-4-6

--provider was removed from run in v2026.8.11. Name the provider in --model, or set provider: in ~/.initrunner/run.yaml to change the default.

Tool Execution Failures

Tool not found

Error: Tool 'search_documents' is not registered

Fix: This usually means the tool wasn't configured in tools, or for search_documents, you haven't added an 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
If the error says 'fastmcp' is required instead, the install has no MCP client. See Missing Extras.

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 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:

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

Old envelope YAML

Files that still start with apiVersion / kind / metadata / spec still run. Convert them when you want:

initrunner doctor --fix PATH --yes

That writes a .bak copy. See Envelope Migration.

YAML Configuration Mistakes

Missing required fields

Error: 'prompt' is required

Every role file needs at minimum:

name: my-agent
model:
  provider: openai
  name: gpt-4o-mini
prompt: Your system prompt here.

Indentation errors

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

# Wrong — tools is not indented under the document
prompt: ...
  tools:        # stray indent; tools must be a sibling of prompt
    - shell

# Correct
prompt: ...
tools:
  - 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 prompt about the expected workflow:

prompt: |
  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:
    use: roles/a.yaml
    then:
      to: b
  b:
    use: roles/b.yaml
    then:
      to: a   # circular!

# Fixed: b ends the chain instead of delegating back
agents:
  a:
    use: roles/a.yaml
    then:
      to: b
  b:
    use: roles/b.yaml

A flow child has no sink block of its own. To have b write its result to a file, declare the sink inside roles/b.yaml:

sinks:
  - 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 then: edge back to a.

Delegate sink not connecting

Error: Delegate target 'consumer' not found in agents

Fix: The to name in a then: edge must exactly match an agent name defined in agents. Check for typos.

Agents not starting in order

Fix: Add after to enforce startup ordering:

agents:
  producer:
    use: roles/producer.yaml
    then:
      to: consumer
  consumer:
    use: roles/consumer.yaml
    after: [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" --format 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