Troubleshooting

export STASO_DEBUG=1   # turn on debug logs before reproducing

403 — "Organization has no active plan"

Ingest returns 403. Dashboard shows no new spans.

Fix: See pricing to subscribe.

Ingest returns 429 with Retry-After. Debug logs show ingest rate limited.

Fix: The SDK honors Retry-After automatically. For sustained overages, see pricing or reduce trace volume.

No errors, no traces.

Cause: Missing API key, missing agent name, enabled=False, or a network block on base_url.

Fix:

Confirm STASO_API_KEY and STASO_AGENT_NAME are set (or passed to st.init).
Check for enabled=False in st.init.
STASO_DEBUG=1 and re-run. Look for ingest returned lines.
Verify outbound HTTPS to https://api.staso.ai.

Cause: Guard fails open by default on transport errors so the SDK never crashes your agent.

Fix: Fail closed per call or globally:

result = st.guard("shell", {"cmd": "rm -rf /"}, fail_closed=True)

export STASO_GUARD_FAIL_CLOSED=true

staso setup succeeded but no traces appear.

Cause: Settings drifted after an SDK upgrade, or wrong scope.

Fix:

staso status            # check which files have Staso hooks
staso sync              # re-apply hooks for the current SDK version

If status shows not configured, re-run staso setup --target <agent> with --scope global. See CLI.

Cause: Vendor SDK is not installed — Staso declares it as an optional extra.

Fix:

pip install "staso[anthropic]"   # or "staso[openai]", or "staso[all]"

CLI agents trace inconsistently or miss events after pip install --upgrade staso.

Cause: Settings file references the old Python path or lacks new hook events.

Fix:

staso sync

staso update does the upgrade and sync in one step.