Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

This page is the canonical troubleshooting and execution-check surface for jhf-keystore.

Run This Check​

Fast local diagnostics:

bash scripts/run.sh probe --mode light
bash scripts/run.sh doctor --mode deep
bash scripts/verify-docs-inventory-adoption.sh
bash scripts/verify-runtime-materialization-drift.sh

Host-gated diagnostics:

VW_RUNTIME_DRIFT_VERIFY_LIVE=1 bash scripts/verify-runtime-materialization-drift.sh
VW_PROJECTION_VERIFY_LIVE=1 bash scripts/verify-vaultwarden-projection-presence.sh
VW_SSO_VERIFY_LIVE=1 bash scripts/verify-vaultwarden-sso-consumer-contract.sh

Common Failure Modes​

bw CLI missing or broken​

Symptoms:

  • probe or doctor exits non-zero
  • resolve reports missing bw

Checks:

bash scripts/setup.sh
bash scripts/run.sh probe --mode light --json

Recovery:

  • reinstall or re-expose bw
  • set VW_BW_BIN only to a trusted local binary path

Runtime materialization drift​

Symptoms:

  • verify scripts report repo/compose/container/app mismatch

Checks:

bash scripts/verify-runtime-materialization-drift.sh

Recovery:

  • compare repo truth in contracts/runtime-stack-contract.json
  • compare active compose/runtime materialization on the host
  • if the mismatch is environment-owned, route externally instead of masking it here

Projection / identity drift​

Symptoms:

  • projected Helpifyr organization or principals missing

Checks:

bash scripts/verify-vaultwarden-projection-presence.sh

Recovery:

  • treat missing/stale projection as fail-closed
  • route to upstream owner repos when projection truth is absent

Docs posture drift​

Symptoms:

  • Fabric inventory reports partial docs readiness

Checks:

python3 scripts/validate-docs-inventory-adoption.py

Recovery:

  • restore the canonical docs family
  • update docs/docs.manifest.yaml
  • update root docs_manifest.yml

Verify After Fix​

After any fix, rerun:

python -m pytest -q
bash scripts/verify-docs-inventory-adoption.sh
bash scripts/verify-runtime-materialization-drift.sh

AGPLv3. See LICENSE (LICENSE).

Learn more at helpifyr.com.