Textbook 16 Troubleshooting And FAQ

Troubleshooting And FAQ

This chapter turns the troubleshooting decision tree into a field playbook. Use it when a command, policy, GUI page, evidence bundle, connector, or AISPM readiness packet does not behave as expected.

Triage First

Start with four questions:

1. Is the issue in the decision, the enforcement point, the evidence, or the reporting layer?
2. Can you reproduce it with the CLI?
3. Does cavra policy explain match the decision you expected?
4. Is the evidence fresh, signed, and tied to the action you are investigating?

Decision Problems

Symptom	Likely cause	First command	Fix
Safe action is denied	Rule is too broad or default is deny.	cavra policy explain <action> <target>	Add a narrower allow rule before the broad rule.
Risky action is allowed	Missing path, command, branch, or MCP rule.	cavra policy explain <action> <target>	Add explicit deny or approval routing.
Approval expected but not created	Rule returns allow or deny.	cavra evaluate <action> <target> --json	Change decision to requires_approval and define route.
Shadow mode records but does not block	Policy mode is shadow.	Inspect policy mode.	Move to enforce after rollout validation.

Evidence Problems

Symptom	Likely cause	Fix
cavra evidence verify fails	Missing trust root, wrong key ID, stale signature, or altered bundle.	Verify trust root path and key ID before regenerating evidence.
Evidence does not mention policy	Decision was generated without policy pack metadata.	Re-run evaluation with the intended policy pack loaded.
Evidence exists but CI fails	CI reads a different bundle path.	Align CI path, bundle output, and PR attestation configuration.
Evidence is stale	Bundle was generated before the current release or decision.	Regenerate evidence and rerun readiness checks.

Approval Problems

Symptom	Likely cause	Fix
Pending request is not visible	Wrong store, route, tenant, or state filter.	Run cavra approval list --state pending.
Approval expired too quickly	Route TTL is too short for the workflow.	Adjust expires_after for the route.
Break glass looks like a bypass	Missing reason, actor, or incident reference.	Require break-glass justification and review it after the incident.
Provider delivery failed	Connector or credentials failed.	Preserve failed delivery evidence and retry through approved provider settings.

GUI And Sandbox Problems

Symptom	Likely cause	Fix
Page loads but data looks old	Browser cache or static sample state.	Hard refresh and confirm the correct local build or hosted page.
Screenshot does not match docs	Local sandbox is from a different commit.	Rebuild or serve the current apps/sandbox-ui content.
AISPM page shows sample data	Public sandbox is intentionally public-safe.	Use Enterprise live ingestion for tenant-specific production posture.
Export button produces public sample packet	Running Community sandbox, not Enterprise tenant workflow.	Use Enterprise report delivery validators for real delivery evidence.

Connector And SMTP Problems

Symptom	Likely cause	Fix
SMTP validation fails authentication	Wrong username, password, app password, host, port, or TLS mode.	Confirm provider settings and use environment variables or a secret store.
Report sent but not received	Recipient policy, spam filtering, DNS, or provider delay.	Check provider delivery logs and recipient mailbox.
SIEM or ITSM event missing	Connector endpoint, token, or payload schema mismatch.	Validate connector payload against the public contract and preserve failed audit evidence.
Secret appears in logs	Redaction is incomplete.	Stop the run, rotate the secret, and fix redaction before rerunning.

AISPM Readiness Problems

Blocker	What it means	Closeout action
Missing live connector evidence	Synthetic fixtures were used instead of real providers.	Run connector validation with approved real settings.
Tenant isolation unproven	Tenant data boundaries were not tested.	Run isolation checks with at least two real tenant scopes.
Runtime workflow synthetic only	Validators did not see real agent/tool execution.	Run file, command, Git, MCP, approval, and evidence workflows through CAVRA.
Report delivery unverified	Report packet was generated but not delivered and audited.	Send to approved recipients and capture delivery audit evidence.
Evidence stale	Evidence predates the release or pilot decision.	Regenerate source evidence and rerun final readiness gate.

FAQ

Is CAVRA only for AI coding agents?

No. Coding agents are the most visible use case, but the model applies to any agentic workflow that can touch files, shell, Git, cloud, CI/CD, MCP tools, reports, or operating systems.

Does CAVRA replace code review?

No. CAVRA evaluates runtime authority before action and produces evidence. Code review, SAST, SCA, secrets scanning, CSPM, IAM governance, and incident response still matter.

Why did CAVRA block a command that a human can run?

CAVRA is governing agent authority, not human shell access in general. A command may be legitimate for a human with context but too risky for unattended agent execution.

Can Community Edition prove production readiness?

Community Edition can teach the model, enforce local decisions, and create evidence. Full production readiness still requires Enterprise validation for real connectors, tenants, report delivery, identity, and runtime workflows.

Can I use animated diagrams in the wiki?

Yes, where GitHub renders SVG image assets. The diagrams in this textbook are SVG-native and degrade to static diagrams when animation is disabled by browser settings or renderer policy.

Check Your Understanding

1. What is the first command to run when a decision surprises you?
2. Why should failed connector deliveries still produce evidence?
3. What does an AISPM readiness blocker usually mean?
4. Why is stale evidence not enough for a production gate?

What's Next

Finish with Conclusion: The Runtime Authority Revolution, which turns the technical model into an operating call to action.