Troubleshooting

Traces Not Showing Up

1. Check API key and URL:

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:

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:

pip install "staso[anthropic]"

Call patch_anthropic() before creating your Anthropic client:

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

OpenAI Integration Not Working

Install the extra:

pip install "staso[openai]"

Call patch_openai() before creating your OpenAI client:

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:

@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:

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:

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.

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

On this page