Troubleshooting

“Connection refused”

Your agent cannot reach the TapPass server.

Symptoms

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

or

tappass.errors.TapPassConnectionError: Failed to connect to TapPass

Causes and fixes

Cause	Fix
TapPass server is not running	Check with your platform team. Run curl https://tappass.example.com/health to verify.
Wrong URL	Verify the URL in your Agent(url=...) constructor or TAPPASS_URL env var. The SDK defaults to http://localhost:9620 when nothing is set.
Network / firewall	Ensure your agent can reach the server. Check VPN, firewall rules, and DNS resolution.
TLS certificate	With self-signed certs, point your HTTP client’s CA bundle at your internal CA (the SDK uses httpx, which respects SSL_CERT_FILE). Development only.

Quick diagnostic

# 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

SDK resilience

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.

---

“Policy blocked my request”

A governance pipeline step blocked your request.

Symptoms

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"
  }
}

How to read the block reason

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)

Common blocks and fixes

Step	Block reason	Fix
detect_pii	PII in prompt or response	Remove PII from the prompt, or have your platform team change the step action from block to redact.
detect_secrets	API key / password in prompt	Remove secrets from prompt text. Use tool calls to access secrets.
detect_injection	Prompt injection detected	Review your prompt for injection patterns. If it is a false positive, your platform team can adjust the threshold.
rate_limit	Too many requests	Wait and retry. See Rate limited below.
budget_enforcement	Token budget exceeded	Contact your platform team to increase the budget.
content_safety	Unsafe content	Review the content. Content safety blocks cannot be overridden by flags.
filter_tools	Tool not allowed	The agent’s policy does not permit this tool. Contact your platform team.

Adjusting policy (platform team)

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.

Verifying a block was real

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

---

“Token expired”

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

Symptoms

Authorization failed: Token expired at 1711500000

How TTL works

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

Fixes

Cause	Fix
Token too short-lived	Increase TTL when minting the token (talk to your platform team)
Clock skew	The token scheme tolerates a small amount of clock skew — keep the agent’s clock NTP-synced.
Token not refreshed	Implement token refresh logic — request a new token before the old one expires

SDK cache behavior

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.

---

“Pipeline timeout”

The governance pipeline took too long to process your request.

Symptoms

Pipeline timeout after 120s

Timeout configuration

Setting	Default	Description
Total pipeline timeout	120 seconds	Maximum time for all steps combined
Request timeout (SDK)	30 seconds	Fixed in Agent.stream(); govern() enforce calls use 5s, approval long-polls up to wait_approval(timeout_seconds=300)

Which steps are slow?

Steps that can be slow:

Step	Why it is slow	Fix
call_llm	Waiting for the LLM provider	Not a pipeline issue — the provider is slow. Try a faster model.
inspect_images	Image analysis for multimodal requests	Disable if you do not send images: "inspect_images": {"enabled": false}
external_detection	Calling an external detection API	Check network latency to the external service
detect_injection	Injection detection on long prompts	Sensitivity is tunable by your platform team
content_safety	Content moderation on long prompts	Increase threshold or skip for trusted agents

Disabling expensive steps

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.

---

“Rate limited”

Too many requests in the configured time window.

Symptoms

{
  "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 limit configuration

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

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

Per-agent vs per-org limits

Scope	How it works
Per-agent	Each agent has its own counter. Agent A hitting its limit does not affect Agent B.
Per-org	All agents in the organization share a pool. One agent can exhaust the limit for all.
Per-user	Rate limits scoped to the end-user making the request through the agent.

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

What to do

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.