Troubleshooting (commercial layer)¶
Audience: DevOps, developers, and on-call engineers.
When you are done: You can map a failure to an exit code, the responsible layer (public vs commercial), and the next fix.
The authoritative exit code list lives in the public engine:
This page covers commercial-specific failures and points to public docs for the rest.
Exit code quick reference¶
| Code | Layer | Commercial? | Doc |
|---|---|---|---|
| 0 | Public | — | Success |
| 1 | Public | — | Generic error |
| 2 | Public | — | Pre-flight failure |
| 3 | Public | — | Config validation |
| 4 | Public | — | Invalid salt |
| 5 | Commercial | License / entitlement | Licensing |
| 6 | Commercial | Drift detected | Drift detection |
| 130 | Public | — | Interrupted |
Message format (all codes): Context + Cause + Remediation — see public doc.
Commercial failures¶
Exit 5 — license / entitlement¶
| Cause | Remediation |
|---|---|
| Image is 1.0.10 or older | Upgrade to 1.0.11+. Earlier images reused one CheckoutLicense ClientToken across tier probes, so entitled buyers got ValidationException/NoEntitlementsAllowed and failed closed. Fixed in 1.0.11 |
| No valid license configured | Attach an IAM task role with license-manager:CheckoutLicense, or set a PRIVACI_LICENSE_KEY JWT — see Licensing |
Service role not found on CheckoutLicense |
One-time License Manager account setup — below |
| Provisional lease still held (concurrent run / prior crash) | A single-count entitlement allows one provisional checkout at a time (≤60 min TTL). Avoid concurrent jobs; retry after the lease self-expires |
| Expired or invalid JWT | Re-issue license; verify PRIVACI_LICENSE_PUBLIC_KEY |
| Feature not in tier | Config uses a capability your tier lacks — upgrade to Compliance, or remove the gated feature |
Details: Licensing & entitlement
License Manager one-time account setup¶
Audience: Every buyer AWS account, once, before the first PrivaCI run.
Marketplace subscribe creates your license in License Manager, but AWS may
not enable the License Manager service-linked roles until you complete a
one-time setup. Without them, CheckoutLicense fails (CLI or container → exit
5).
| Symptom | Not this |
|---|---|
Service role not found. Consult setup procedures in License Manager… |
Launch step 3 task role — that is separate (quick-launch creates it) |
Fix:
- Console → License Manager → Start using License Manager → grant permissions, or
- CLI (same account that subscribed):
aws iam create-service-linked-role --aws-service-name license-manager.amazonaws.com
aws iam create-service-linked-role --aws-service-name license-management.marketplace.amazonaws.com
Also documented in Deploy on AWS ECS (License Manager setup).
Exit 6 — drift¶
Applies when the CLI or your script treats drift as a hard gate.
| Cause | Remediation |
|---|---|
| Schema changed since last run | Review findings; update mask-rules.yaml (re-run privaci plan after edits) |
uncovered_pii_column |
Add masking rule before next run — or re-scaffold with privaci init --force and re-review |
Details: Drift detection
Report signing / verify errors¶
| Symptom | Remediation |
|---|---|
CommercialConfigError — bad PEM |
Regenerate Ed25519 key — Signed reports |
| Verify signature mismatch | Report tampered or wrong public key |
TARGET_DB_URL missing for report |
Set target DSN |
Plugins not active¶
| Symptom | Remediation |
|---|---|
| Unsigned reports only | Confirm you are running the Marketplace image, not the public community GHCR image |
| Exit 5 on every run | Confirm the Marketplace subscription is active and the task role can call license-manager:CheckoutLicense — Licensing |
drift_detector is None |
Commercial layer not in the image — contact support; verify image URI from subscription |
Contributors: verify plugins after editable install:
python -c "from privaci.contracts import load_plugins as l; p=l(); print(type(p.report_renderer).__name__)"
# Expect: SignedJsonReportRenderer (not JsonReportRenderer)
See public Extending PrivaCI.
Public engine failures (pointers)¶
| Symptom | Public doc |
|---|---|
| Config rejected | Prefer scaffold with init; then public Configuration |
| Connection / catalog errors | CLI reference |
| Masking quality concerns | privaci verify |
| Resume / interrupted run | Error 130 + privaci resume |
_privaci schema / grants |
State schema |
FAQ¶
Where do I start debugging a failed run?
1. Note exit code → public error codes
2. Check _privaci.runs.status on target
3. Re-run with privaci dry-run --report /tmp/review.md
Logs contain PII?
They should not. Public engine redacts PII in observability — see
Observability.
File an issue if you see raw values.
Commercial support boundary?
Engine bugs → public repo. License, reports, drift, entitlement → commercial
layer (this repo).