---
title: Troubleshooting
description: Common issues and how to fix them.
---

# Troubleshooting

## Traces Not Showing Up

**1. Check API key and URL:**

```python
st.init(api_key="ak_...", base_url="https://api.staso.ai", ...)
```

**2. Call `st.shutdown()` before exit.** Without it, traces can be lost if the process exits before the background sender finishes.

**3. Turn on debug logging:**

```python
st.init(..., debug=True)
```

Look for `ingest returned 401` (bad API key) or `ingest error` (network issue).

**4. Make sure `enabled` isn't `False`.**

## Anthropic Integration Not Working

Install the extra:

```bash
pip install "staso[anthropic]"
```

Call `patch_anthropic()` **before** creating your Anthropic client:

```python
st.init(...)
st.integrations.patch_anthropic()  # First
client = anthropic.Anthropic()     # Then this
```

## OpenAI Integration Not Working

Install the extra:

```bash
pip install "staso[openai]"
```

Call `patch_openai()` **before** creating your OpenAI client:

```python
st.init(...)
st.integrations.patch_openai()     # First
client = openai.OpenAI()           # Then this
```

## Missing Tool Inputs/Outputs

All three decorators capture inputs and outputs by default. If you've disabled capture:

```python
@st.tool(name="search", capture_input=False)   # No input capture
def search(query: str) -> str: ...

@st.tool(name="search")                         # Full capture (default)
def search(query: str) -> str: ...
```

## Queue Full Warnings

Your agent is emitting spans faster than they can be sent. Options:

```python
st.init(
    ...,
    max_queue_size=50_000,   # Bigger buffer
    batch_size=500,          # More per request
    flush_interval=1.0,      # Send more often
)
```

## Claude Code Integration Not Tracing

**1. Check that setup completed:**

```bash
staso setup --target claude-code --api-key ak_... --scope global
```

**2. Verify the API key is set.** Open `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project) and confirm `STASO_API_KEY` appears in the `env` section.

**3. Enable debug logging.** Set `STASO_DEBUG=1` in the same `env` section, then start a Claude Code conversation. Look for `staso:` prefixed log lines in stderr.

**4. Check scope.** If you used `--scope project`, the hooks only apply in that project directory. Use `--scope global` to trace all conversations.

## Python Version

The SDK needs Python 3.11+. Check with `python --version`.

## Something Else?

The SDK is designed to never crash your application — all SDK code paths catch exceptions silently. If you're seeing SDK-related errors, open an issue at [github.com/staso-ai/python-sdk](https://github.com/staso-ai/python-sdk/issues).

Your exceptions always propagate normally. The SDK records them on the span but never swallows them.
