Control CoreDocs

🛠️ Troubleshooting Controls

Audience: Control authors, DevOps, security engineers Related: Troubleshooting Overview · Admin Troubleshooting

📌 Actions

Action did not fire

  1. Confirm BOUNCER_ENABLE_POST_DECISION_ACTIONS is not false in Bouncer config
  2. Verify the action trigger matches the expected decision outcome (on_allow, on_deny, on_mask, on_error, always)
  3. Check Bouncer logs: docker compose logs bouncer | grep POST_DECISION_ACTION
  4. Confirm config.destination_ref and config.credential_ref in the action point to valid, active integrations in Settings → Integrations

📌 PIP attributes

Missing PIP attributes in Visual Builder

  1. Confirm the data source connection is Active in Settings → Data Sources
  2. Verify the attribute mapping uses the correct target_attribute and data_type
  3. Check the last sync timestamp — click Sync Now to force a refresh
  4. In the Wizard Context Enrichment panel: select the PIP Connection first, then map Attribute/Endpoint to Target Path (the connection must be selected first for attributes to appear)

Attribute resolves to undefined at runtime

  • Confirm the target attribute name in the mapping exactly matches what the control references (e.g. user.department, not user.dept)
  • Check runtime_tier — if snapshot, confirm the latest sync populated the value
  • For decision_time tier: confirm the data source is reachable from the Bouncer at runtime

📌 Semantic Explorer

No columns appear in Semantic Explorer

  1. Click Refresh Auto-Tags for the selected data source
  2. Confirm the connection test succeeds and schema discovery returns tables/columns
  3. Verify provider credentials have metadata-read permissions (read-only is preferred)
  4. If using manual overrides: ensure table/column names exactly match the discovered schema

Auto-tags look incorrect

  • Use manual override in Semantic Explorer (click a tag → Override → Save)
  • Add a short override reason for audit traceability
  • Re-run a simulation with a generated test case to confirm the control evaluates correctly after the override

📌 Simulator

"Generate Test Case" button is greyed out or fails

  • Confirm the control has at least one valid condition with an input attribute (e.g. input.subject.department)
  • Confirm at least one data source has synced successfully
  • Browser network panel: check POST /v1/pis/policies/{id}/generate-test-case for the error response

Denial replay is empty

  • Confirm audit logs include DENY or FAILURE outcomes in the selected environment
  • Verify the selected environment matches the Bouncer's ENVIRONMENT setting
  • Send a few test requests through the Bouncer in sandbox, then retry
  • Use Manual Payload Mode if no denial records are available yet

Denial explanation not shown

  • Explanations are generated only for DENY outcomes
  • Confirm trace data is present in the simulation result panel
  • Browser network panel: check POST /v1/pis/policies/{id}/explain-denial returns HTTP 200

Decision evaluates to undefined or No Match

  • The control has no matching condition for the provided input — treated as implicit deny
  • Add a print() statement in the Rego editor to trace evaluation paths
  • Verify attribute paths match exactly: input.subject.department, not input.user.department
  • Open Semantic Explorer to confirm field names from the data source

📌 Control promotion

Promote button is disabled

  • Confirm the License Server connection is active: Settings → General → Telemetry → Test Connection
  • Confirm the subscription tier is active: Settings → General → Subscription
  • See License Management

Control promotes but does not enforce in production

  1. Confirm the Production Bouncer is linked to this control (Settings → PEPs → Bouncer status)
  2. Verify the Policy Bridge sync completed: the Bouncer should show an updated sync timestamp
  3. Confirm traffic is going through the Bouncer (port 8080), not directly to the resource
  4. Check docker compose logs bouncer | grep -i "policy_sync" for sync errors

Production metadata mismatch after promotion

Controls that rely on PIP attributes can fail in production if the production data source returns different field names or values than sandbox.

  1. Use SCCA: "Compare sandbox vs production metadata values and list parity gaps"
  2. Confirm region, risk_level, kyc_status, and other enum attributes return identical values across environments
  3. Fix mismatches in Settings → Data Sources → Mappings before retrying promotion

📌 Approval gates and break-glass

Requests blocked after enabling approval gate

  1. Check Controls → Approval Inbox for pending approvals
  2. Confirm approver_role is a valid role and approvers can access the Approval Inbox
  3. Verify notification routing: notify_destination_ref must point to a configured destination so approvers are alerted

Break-glass path still fails

  1. Verify break_glass_notify destination references exist and are Active in Settings → Integrations
  2. Confirm reason and TTL requirements are aligned with your runbook
  3. Pair break-glass with audit_log on on_deny to capture decision evidence for each emergency request
  4. If rollout is new: temporarily use alert-only actions (audit_log + notification) before enabling hard enforcement

📌 SCCA

SCCA guidance seems too generic

  • Provide resource and control context in your prompt: "For the control finance-read-access on resource Data API, add a condition…"
  • Ask for explicit wizard tab actions: "In the Conditions tab, add a condition for user.department equals Finance"
  • If SCCA does not see your PIP attributes: confirm the data source has synced recently