← Back to Documentation

Troubleshooting

Common errors and how to fix them.

Installation Errors

"No module named 'anthropic'" (or 'openai')

You need to install the provider SDK for models in your paths.

pip install anthropic  # For Claude models
pip install openai     # For GPT models
pip install huggingface_hub  # For HuggingFace models

"Python version 3.9 is not supported"

Kalibr requires Python 3.10 or higher.

python --version  # Check your version

If you're on 3.9, upgrade Python or use pyenv/conda to manage versions.

Authentication Errors

"Invalid or missing API key"

  1. Check that KALIBR_API_KEY is set correctly
  2. Make sure you copied the full key from the dashboard (click the Copy button)
  3. Verify the key is active in Dashboard → Settings
echo $KALIBR_API_KEY  # Should show your key

"401 Unauthorized" on provider calls

Your provider API key is missing or invalid.

echo $OPENAI_API_KEY     # For GPT models
echo $ANTHROPIC_API_KEY  # For Claude models
echo $HF_TOKEN           # For HuggingFace models

Runtime Errors

"Outcome already reported" warning

This warning appears if you call report() more than once for the same request. It's usually harmless but indicates a logic issue in your code.

Fix: Make sure you only call report() once per completion() call.

Routing not changing after many runs

Kalibr needs ~20-50 outcomes per path before routing becomes stable. During the "Learning" phase, it explores randomly.

Check: Go to Dashboard → your agent → verify sample counts are increasing.

Dashboard Issues

Agent not appearing in dashboard

  1. Verify your KALIBR_TENANT_ID matches what's shown in Dashboard → Settings
  2. Check that report() is being called after each completion
  3. Wait 30 seconds and refresh - there may be a small delay

Dashboard shows old data

Hard refresh the page (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows).

Failure Categories & Insights

failure_category validation error

  • Symptom: ValueError when calling report() or report_outcome()
  • Cause: Invalid failure_category value
  • Fix: Use a value from FAILURE_CATEGORIES: timeout, context_exceeded, tool_error, rate_limited, validation_failed, hallucination_detected, user_unsatisfied, empty_response, malformed_output, auth_error, provider_error, unknown

update_outcome returns 404

  • Symptom: 404 when calling update_outcome()
  • Cause: No outcome exists for the given trace_id + goal combination
  • Fix: Ensure the original outcome was reported first with report_outcome() or router.report()

Insights returns insufficient_data

  • Symptom: All goals show status "insufficient_data"
  • Cause: Fewer than 10 outcomes reported for each goal
  • Fix: Report more outcomes. Kalibr needs at least 10 per goal to calculate meaningful statistics.

Still Stuck?

  • Check the FAQ for more answers
  • Open an issue on GitHub
← Back to Documentation