Troubleshooting
Resolve the most common first-run failures before you move deeper into governance, proof, or readiness.
Start with the failure shape
| If the problem looks like... | Check this first | Then continue to |
|---|---|---|
| The request never reaches OSuite | base URL, API key, workspace scope | Connect a runtime |
| The request reaches OSuite but no review appears | requires_approval, decision tier, policy mode | Approval flow |
| The decision closes but proof export is missing | proof destination, artifact route, export settings | Artifacts and fields |
| The buyer story feels unclear | authority boundary, workspace governance, assurance pack | PCAA, Enterprise assurance |
| Readiness pages feel abstract too early | onboarding not yet complete | Getting started, Readiness |
Common first-run failures
Invalid or internal base URL
Symptoms:
- requests fail immediately
- environment examples point to a non-public domain
- callbacks or redirects resolve to the wrong host
What to do:
- Confirm
OSUITE_BASE_URLpoints to the intended public or local host. - Re-run the smallest low-risk decision.
- Only continue once the same base URL works across request, review, and export.
Wrong workspace credential scope
Symptoms:
- runtime connects but artifacts do not appear where expected
- approval or export surfaces look empty
- the decision path is visible in one workspace but not another
What to do:
- Confirm the API key belongs to the same workspace you are inspecting.
- Retry the first decision with a single known workspace identifier.
- Check the approval and artifact surfaces again before moving on.
Approval never triggers
Symptoms:
- you expected a reviewer step but the decision auto-closed
- medium-risk or high-risk decisions do not route into the queue
What to do:
- Verify
requires_approvaland the intended decision tier. - Confirm the destination type and policy mode match the scenario you are testing.
- Compare the result against the approval models in
Approval flow.
Proof bundle is missing or incomplete
Symptoms:
- the request can be replayed but not exported
- receipts exist but buyer-facing artifacts are missing
- artifact fields feel inconsistent across pages
What to do:
- Check the configured proof destination.
- Confirm the decision and approval receipts both closed successfully.
- Open
Artifacts and fieldsto compare expected bundle structure.
When to stop troubleshooting and go deeper
Move on only when all of the following are true:
- one runtime can submit a governed decision reliably
- one approval or auto-allow path is readable
- one receipt path can be explained without translation
- one proof or artifact surface is visible
If those four conditions hold, continue into PCAA, Workspace governance, or Readiness depending on your goal.