TraceLLM
Documentation

Troubleshooting

Common issues and debugging paths for TraceLLM.

MONGO_URL not set

If you see a warning that traces are not being persisted, the most likely cause is a missing or incorrect MONGO_URL environment variable.

Why it happens:

TraceLLM requires a MongoDB connection to store trace data. When MONGO_URL is not set or points to an unreachable server, the @trace decorator and CLI complete their work in memory but the trace is never saved to the database.

How to fix it:

  1. Create a .env file in your project root
  2. Add your MongoDB connection string and database name
  3. Restart the TraceLLM stack with tracellm start
.envCopy
bash
# Example .env file
MONGO_URL=mongodb://localhost:27017
DB_NAME=tracellm

Tracey Troubleshooting

Use mongosh --eval "db.runCommand({ ping: 1 })" to test your MongoDB connection. If it fails, check that your MongoDB instance is running and the URL is correct.

Common Issues

IssueCauseSolution
tracellm: command not foundPython bin directory not in PATHVerify pip install location and add to PATH: export PATH=$PATH:$HOME/.local/bin
ModuleNotFoundError: No module named 'tracellm'Package not installed or wrong environmentRun pip install tracellm and check your virtual environment
MongoDB connection refusedMongoDB not running or wrong MONGO_URLStart MongoDB: mongod or docker run -p 27017:27017 mongo:7
Dashboard shows blank pageFrontend build issue or port conflictCheck browser console for errors, run tracellm start --dashboard-port 3001
WebSocket won't connectBackend not running on expected portEnsure tracellm start is running and check the port
Port 8000 already in useAnother process using the portUse tracellm start --port 8001
No traces in dashboardNo traces recorded or filter mismatchRun tracellm trace 'test' and check filters in dashboard
Trace persistence skippedMongoDB is unavailable or MONGO_URL not setSet MONGO_URL and DB_NAME, start MongoDB, restart the stack
ImportError for openai packageOpenAI extra not installedRun pip install 'tracellm[openai]' or pip install openai>=1.6.0
LangChain callback not capturing stepsCallbacks not passed in configAdd config={'callbacks': [handler]} to every chain/tool.invoke() call

Diagnostic Steps

If you encounter unexpected behavior, follow these diagnostic steps:

1

Check the Stack Status

Run tracellm start --check to verify all services are running. This performs health probes without keeping the process running.
2

Verify Environment Variables

Ensure MONGO_URL, DB_NAME, and provider API keys (OPENAI_API_KEY, etc.) are correctly set.
3

Check MongoDB Connectivity

Use mongosh to connect directly to your MongoDB instance and verify the traces collection exists.
4

Generate a Test Trace

Run tracellm trace "diagnostic test" and check console output for the trace summary panel.
5

Replay the Trace

Use tracellm replay {trace_id} to verify the trace was persisted and can be reconstructed.

Getting Help

If the diagnostic steps do not resolve your issue:

  • Check the backend logs — the FastAPI server outputs detailed error messages to stderr
  • Run tracellm --version to confirm your installed version
  • Review the FAQ for additional answers

Info

When reporting issues, include the output of tracellm --version, your Python version, MongoDB version, and the full error message for fastest resolution.
Previous

FAQ