Troubleshooting

Your agent cannot reach the TapPass server.

ConnectionError: Connection refused, https://tappass.example.com

or

tappass.errors.TapPassConnectionError: Failed to connect to TapPass

Start with the built-in check, which reports your configured server and whether it is reachable:

tappass status

Or probe the server directly:

# Check if TapPass is reachable (root-level health for load balancers)
curl -s https://tappass.example.com/health | python -m json.tool

# Readiness / liveness probes (dependencies vs. process-alive)
curl -s https://tappass.example.com/api/health/ready
curl -s https://tappass.example.com/api/health/live

# Verify audit-trail integrity (hash chain check)
curl -s -H "Authorization: Bearer tp_abc123..." \
  https://tappass.example.com/api/audit/integrity

If your agent must keep operating when TapPass is temporarily unavailable, use the resilience layer. Note that ResilienceManager is standalone, Agent has no resilience= constructor parameter:

from tappass.resilience import ResiliencePolicy, ResilienceManager, FailMode

manager = ResilienceManager(
    ResiliencePolicy(mode=FailMode.FAIL_OPEN_CACHED),
)
# Wire manager.record_success() / manager.handle_connection_failure(...)
# around your TapPass HTTP calls. See the reference for the full pattern.

For govern(mode="enforce") tool calls, an unreachable /v1/govern fails closed with GovernanceUnavailable unless you set TAPPASS_FAIL_OPEN=1.

See SDK Resilience for details.

A governance pipeline step blocked your request.

tappass.PolicyBlockError: Request blocked by detect_pii, PII detected in prompt

or in the HTTP response:

{
  "error": {
    "message": "Request blocked by policy",
    "type": "policy_block",
    "blocked_by": "detect_pii",
    "reason": "PII detected: EMAIL, PHONE_NUMBER"
  }
}

Every block includes:

• blocked_by, which pipeline step blocked the request (e.g. detect_pii, detect_secrets, rate_limit)
• reason, human-readable explanation
• classification, data classification that triggered the block (e.g. CONFIDENTIAL)

Platform teams can adjust step behavior through policy configuration:

{
  "steps": {
    "detect_pii": {
      "on_detection": "redact"
    }
  }
}

The on_detection action can be: block, redact, notify (log and continue), or allow.

If you suspect a block was recorded incorrectly, check the audit trail, every GovernanceDecision exception carries audit_url and the correlation IDs (session_id, task_id, agent_uuid, pipeline_uuid). You can also verify the hash chain end-to-end:

curl -s -H "Authorization: Bearer tp_..." \
  https://tappass.example.com/api/audit/integrity

A capability token has exceeded its time-to-live (TTL).

Authorization failed: Token expired at 1711500000

Capability tokens are short-lived and expire; when a token expires, the agent must request a new one from the control plane.

The SDK caches responses for resilience purposes (not for performance). Its TTL is separate from token TTL and configurable via TAPPASS_CACHE_TTL.

The cache is used only when TapPass is unreachable, under fail-open-cached mode.

The governance pipeline took too long to process your request.

Pipeline timeout after 120s

Steps that can be slow:

Platform teams can disable steps in the pipeline configuration:

{
  "steps": {
    "inspect_images": { "enabled": false },
    "external_detection": { "enabled": false }
  }
}

Or have the platform team run the affected steps in shadow mode, decisions are computed and logged but not enforced.

Too many requests in the configured time window.

{
  "error": {
    "message": "Rate limit exceeded: 105/100 calls in 3600s",
    "type": "policy_block",
    "blocked_by": "rate_limit"
  }
}

or for token budgets:

{
  "error": {
    "message": "Token rate limit exceeded: 1,050,000/1,000,000 tokens in 3600s"
  }
}

Rate limits are configured per-organization in the pipeline policy:

{
  "steps": {
    "rate_limit": {
      "max_calls": 100,
      "window_seconds": 3600,
      "max_tokens": 1000000
    }
  }
}

The scope is determined by how the rate limit key is configured. By default, limits are per-agent.

1. Wait. Rate limits use a sliding window. Once the oldest requests fall outside the window, new requests are allowed.
2. Check your usage. Use the audit trail to see how many requests your agent is making.
3. Request a higher limit. Contact your platform team to increase the cap.
4. Optimize your agent. Reduce unnecessary LLM calls, cache results client-side, batch requests, use cheaper models for simple tasks.