Troubleshooting

Common errors, debugging tips, and frequently asked questions.

Common Errors

Error	Cause	Fix
ShieldBlockedError	A scan or policy check blocked the action	Check `e.scan_result` and `e.policy_result` on the exception. Adjust policies or handle the block in your code.
"RUNE_API_KEY not set"	No API key provided via constructor or environment	Set `RUNE_API_KEY` env var or pass `api_key` to `Shield()`.
Connection timeout	Cannot reach Rune cloud endpoints	Check network connectivity. The SDK defaults to fail-open after `connection_timeout_seconds` (default: 10s).
"L2 scanner not available"	Vector similarity dependencies not installed	Install extras: `pip install "runesec[vector]"`
"Policy sync failed"	Cannot fetch policies from cloud	Check API key permissions. Use `local_policies_path` as a fallback.

Debug Mode

Enable debug mode to log all scan results, policy evaluations, and event emissions to stderr.

Enable via constructorpython

shield = Shield(debug=True)

Enable via environment variablebash

export RUNE_DEBUG=1

Debug output includes scan latencies, threat details, policy match results, and event batch status. Useful for diagnosing false positives or tuning thresholds.

Check SDK Stats

Use shield.stats to check the health of your integration at any time:

print(shield.stats)
# {
#   "events_sent_total": 42,
#   "events_failed_total": 0,
#   "scans_total": 100,
#   "blocks_total": 3,
#   ...
# }

Local-Only Mode

Run the SDK without any cloud connectivity for testing or air-gapped environments:

shield = Shield(
    events_enabled=False,            # disable event emission
    local_policies_path="./policies", # load policies from disk
)

# Scanning works fully offline — L1 and L2 run locally
result = shield.scan_input("test input")
print(result.blocked, result.risk_score)

FAQ

What is the scanning latency?

L1 (regex) scanning typically completes in 1-3ms. L2 (vector similarity) adds 5-10ms. L3 (LLM judge) depends on your LLM provider and is async by default to avoid blocking.

Does the SDK fail-open or fail-closed?

By default, fail-open. If Rune cloud is unreachable, the SDK logs a warning and allows the action to proceed. To fail-closed, set on_block="raise" and handle timeout exceptions in your code.

Can I use Rune without cloud connectivity?

Yes. Set events_enabled=False and use local_policies_path for policies. L1 and L2 scanning work fully offline.

How long are events stored?

Events are stored in ClickHouse for 90 days by default. Dashboard data in Convex (agents, alerts, policies) is retained indefinitely.

Can I adjust L2 thresholds?

Yes. Set l2_block_threshold (default: 0.85) and l2_flag_threshold (default: 0.70) in ShieldConfig. Lower values are more sensitive, higher values reduce false positives.

How do I handle false positives?

Mark alerts as false_positive in the dashboard. This automatically creates an allowlist entry that feeds back to the SDK scanners. You can also adjust scanner thresholds or use action: alert instead of action: block in your policies while tuning.