---
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. An `atexit` hook runs as a fallback, but explicit shutdown is more reliable.

**3. Turn on debug logging:**

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

Look for `ingest returned 401` (bad API key), `ingest returned 5xx` (server error, retried automatically), 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 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:

```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 current status:**

```bash
staso status --target claude-code
```

**2. If not configured, run setup:**

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

Or use the interactive wizard: `staso setup`

**3. 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.

**4. Sync hooks after upgrading:**

```bash
staso update
```

Or manually:

```bash
pip install -U staso
staso sync
```

**5. 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.

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

**7. To start fresh:**

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

## Codex Integration Not Tracing

**1. Check current status:**

```bash
staso status --target codex
```

**2. If not configured, run setup:**

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

Or use the interactive wizard: `staso setup`

**3. Verify hooks file exists.** Check `~/.codex/hooks.json` (global) or `.codex/hooks.json` (project).

**4. Verify feature flag is enabled.** Check `~/.codex/config.toml` contains `codex_hooks = true` under `[features]`.

**5. Sync hooks after upgrading:**

```bash
staso update
```

Or manually:

```bash
pip install -U staso
staso sync --target codex
```

**6. Enable debug logging.** Run a Codex session with `STASO_DEBUG=1` set in the hook command. Look for `staso:` prefixed log lines.

**7. To start fresh:**

```bash
staso uninstall --target codex
staso setup --target codex --api-key ak_... --scope global
```

## 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.
