Documentation

Troubleshooting

Common issues and debugging paths for TraceLLM.

SQLite database not created

If you see a warning that traces are not being persisted, the most likely cause is that the SQLite database could not be created at ~/.tracellm/traces.db.

Why it happens:

TraceLLM uses SQLite to store trace data. The database file is auto-created at ~/.tracellm/traces.db on first run. If the home directory is not writable or the path cannot be created, persistence will fail.

How to fix it:

Check that ~/.tracellm/ exists and is writable
Create it manually: mkdir -p ~/.tracellm
Restart the TraceLLM stack with tracellm start

Verify SQLite databaseCopy

bash

# Verify the database was created:
ls -la ~/.tracellm/traces.db

# Expected output: -rw-r--r--  ...  ~/.tracellm/traces.db

# Inspect tables:
sqlite3 ~/.tracellm/traces.db ".tables"

Tracey Troubleshooting

No environment variables are needed. The database is auto-created at ~/.tracellm/traces.db on first run. Just make sure your home directory is writable.

Common Issues

Issue	Cause	Solution
tracellm: command not found	Python bin directory not in PATH	Verify pip install location and add to PATH: export PATH=$PATH:$HOME/.local/bin
ModuleNotFoundError: No module named 'tracellm'	Package not installed or wrong environment	Run pip install tracellm-cli and check your virtual environment
SQLite database not created	~/.tracellm/ directory is not writable	Create the directory manually: mkdir -p ~/.tracellm
Dashboard shows blank page	Frontend build issue or port conflict	Check browser console for errors, run tracellm start --dashboard-port 3001
WebSocket won't connect	Backend not running on expected port	Ensure tracellm start is running and check the port
Port 8000 already in use	Another process using the port	Use tracellm start --port 8001
No traces in dashboard	No traces recorded or filter mismatch	Run tracellm trace 'test' and check filters in dashboard
Trace persistence skipped	SQLite database could not be created	Check ~/.tracellm/ directory permissions, then restart the stack
ImportError for openai package	OpenAI extra not installed	Run pip install 'tracellm[openai]' or pip install openai>=1.6.0
LangChain callback not capturing steps	Callbacks not passed in config	Add config={'callbacks': [handler]} to every chain/tool.invoke() call

Diagnostic Steps

If you encounter unexpected behavior, follow these diagnostic steps:

Check the Stack Status

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

Verify the Database

Check that ~/.tracellm/traces.db exists and that provider API keys (OPENAI_API_KEY, etc.) are correctly set.

Check Database Tables

Use sqlite3 ~/.tracellm/traces.db ".tables" to verify the traces table exists.

Generate a Test Trace

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

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, SQLite version, and the full error message for fastest resolution.