Troubleshooting

Common issues and how to resolve them. If your problem isn't listed here, reach out on GitHub.

SDK Issues

Traces not appearing in the dashboard

1. Check your API key — make sure TWOSIGNAL_API_KEY is set and starts with ts_
2. Wait a few seconds — traces are processed asynchronously and typically appear within 1–3 seconds
3. Check the SDK isn't disabled — if TWOSIGNAL_ENABLED=false is set, the SDK silently no-ops
4. Flush before exit — the SDK batches events and flushes every 1 second. If your script exits immediately, call ts.flush() before exiting

from twosignal import TwoSignal

ts = TwoSignal()

# ... your code ...

ts.flush()  # ensure all events are sent before exit

ImportError: No module named 'twosignal'

Make sure you installed the SDK with the extras you need:

# base SDK
pip install twosignal

# with specific wrappers
pip install twosignal[openai]
pip install twosignal[anthropic]

# with CLI and TUI
pip install twosignal[cli,tui]

# everything
pip install twosignal[all]

SDK not capturing LLM calls

• Make sure you wrapped the client before making calls: client = wrap_openai(OpenAI())
• Streaming calls (stream=True) are not traced by the OpenAI and Anthropic wrappers — the call still works but no span is created
• Only chat.completions.create() (OpenAI) and messages.create() (Anthropic) are wrapped. Other methods are unaffected.

Cost showing as $0.00

Cost is estimated from token usage and model name. If cost is zero:

• The model name may not be in the pricing table — check supported models for each wrapper
• The LLM response didn't include usage information (some providers omit it for streaming)
• You can submit cost manually via the span's cost field in the REST API

SDK throwing errors in production

The SDK is designed to never throw. All errors are logged internally and swallowed. If you're seeing exceptions:

• Make sure you're using the latest version: pip install --upgrade twosignal
• Check that you're not catching the SDK's internal log output and re-raising
• If the error persists, file an issue with the traceback

CLI Issues

twosignal: command not found

# install with CLI extra
pip install twosignal[cli]

# or run as a module
python -m twosignal_cli

If installed but not found, your Python scripts directory may not be in PATH. Try:

python -m twosignal_cli whoami

Authentication expired

Sessions expire after extended inactivity. Re-authenticate:

twosignal logout
twosignal login

The CLI auto-refreshes tokens, but if the refresh token itself expires, you'll need to log in again.

Connection refused / Cannot connect

• Cloud users: check your internet connection. The API is at https://app.twosignal.dev
• Self-hosted: verify your instance URL is correct: twosignal login --url https://your-instance.example.com
• The CLI will not clear your session on connection errors — you won't lose your login state

Project or org not found

IDs are UUIDs. Make sure you're passing the full ID, not the name:

# list orgs to get the ID
twosignal orgs list

# use the ID, not the name
twosignal projects list --org 550e8400-e29b-41d4-a716-446655440000

TUI Issues

TUI shows garbled output or missing characters

• Use a terminal with 256-color support (iTerm2, Alacritty, Windows Terminal, Kitty)
• Ensure your terminal supports Unicode — the TUI uses box-drawing characters and symbols
• Minimum terminal size is 80×24. Resize your terminal if it's too small.
• On Windows, use Windows Terminal instead of cmd.exe

TUI won't start / crashes on launch

# make sure textual is installed
pip install twosignal[tui]

# try running as a module
python -m twosignal_tui

# check for version conflicts
pip install --upgrade twosignal[tui]

TUI shows "Not authenticated"

Log in via the CLI first, then re-launch the TUI:

twosignal login
twosignal-tui

The TUI and CLI share the same session at ~/.twosignal/session.json.

API Issues

401 Unauthorized

• Check that your API key starts with ts_
• Make sure the key hasn't been revoked (check in dashboard or CLI: twosignal api-keys list --project <id>)
• API keys are project-scoped — a key for Project A won't work for Project B
• The Authorization header format is Bearer ts_your_key (with the Bearer prefix)

429 Rate Limited

You're sending too many requests per second. Check the Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

The Python SDK handles retries automatically with exponential backoff.

413 Payload Too Large

Split large batches into smaller chunks. The SDK does this automatically.

Evaluator Issues

Evaluator not running on new traces

• Check that the evaluator is enabled (toggle it in the dashboard or via CLI)
• Evaluators run asynchronously — scores appear 1–5 seconds after trace ingestion
• LLM Judge evaluators require an OPENAI_API_KEY to be configured on the server

Similarity evaluator always returns 0

The Similarity evaluator requires an expectedOutput to compare against. Make sure your trace or dataset provides one. Without it, the score defaults to 0.

LLM Judge timing out

LLM Judge has a 30-second timeout. If evaluations are timing out:

• Use a faster model (gpt-4o-mini instead of gpt-4o)
• Simplify your criteria — shorter prompts evaluate faster
• Check your OpenAI API key hasn't hit rate limits

Environment Issues

Multiple Python versions

If you have multiple Python versions, make sure the SDK is installed in the right one:

# check which Python is being used
which python
python --version

# install explicitly for a specific version
python3.11 -m pip install twosignal

Virtual environment issues

# create a fresh venv
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# install the SDK
pip install twosignal[all]

Getting Help

• GitHub Issues: github.com/2signal/2signal/issues
• API Status: curl https://api.2signal.dev/api/v1/health
• SDK Version: pip show twosignal
• CLI Version: twosignal --version