Troubleshooting

Support workflow that actually works

# customer machine:
rizmi doctor run --app-name MyApp --json > doctor.json
rizmi app status --app-name MyApp --db "$(rizmi doctor path 2>/dev/null)" # or default location

# send both files to support.

Symptoms → causes → fixes

Symptom / code	Cause	Fix
missing	No license activated yet and trial data absent.	Normal on first contact — the app should have started a trial; if not, check DB permissions at the platformdirs path shown by doctor.
expired	Past exp + grace days.	Issue a new license: rizmi license issue …, then activate in-app or via CLI.
hwid_mismatch	License bound to another machine (OS reinstall also changes the ID).	Get the new rizmi machine-id --raw and re-issue.
tampered	A row/file failed its HMAC or the JWT signature broke.	Re-activate from the original .lic file. If it recurs, the disk may be corrupt — run doctor --strict.
clock_tampering	Clock rolled back past the last observed time.	Correct the system clock (NTP). The ratchet only moves forward.
revoked	License ID on your published CRL.	Remove the ID and publish a fresh list, or re-issue under a new ID.
decode_error	Public key doesn't match the issuing private key.	Verify with rizmi keys verify; re-embed the right public key.
licensed_invalid	A license exists but fails validation (tamper/expiry).	Deliberate behavior: apps never fall back to an active trial once a real license was seen. Deactivate then re-activate a good license.
Doctor: machine-id ✗	Container/VM without OS machine ID.	py-rizmi can't bind HWID here; provide a custom FingerprintProvider.
Doctor: integrity ✗ (state rows)	DB edited outside the app, or copied between machines/apps.	Rows are quarantined automatically. Restore from backup or deactivate/re-activate.
KeyPinError at startup	Embedded key constant and fingerprint disagree — build tampered or developer updated one side only.	Regenerate fingerprint via rizmi keys fingerprint and rebuild both constants together.
Windows: DB "database is locked"	Two processes / AV scanner holding the file.	Connections are short-lived by design; exclude state.db from AV real-time scanning if persistent.

Collecting a support bundle

rizmi doctor run -a MyApp -P pub.pem --fingerprint FP --json > doctor.json
rizmi app status -a MyApp --json > status.json   # add --db for non-default paths

Both files contain no secrets: the public key is public, tokens are hardware-bound, and HMAC values are useless off-machine.