Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

Use this page as the short entrypoint. Detailed procedures remain in the repo-specific runbooks.

Primary References​

  • Runbook
  • Recovery Runbook (docs/RECOVERY_RUNBOOK.md)
  • Operations
  • Environment And Runtime Contract (docs/ENVIRONMENT_AND_RUNTIME_CONTRACT.md)

Runtime Not Ready​

Symptoms:

  • /readyz fails
  • frontend is unreachable
  • runtime bridge or provider cards degrade

Run this check:

docker compose -p jhf-pattern -f docker-compose.v2.yml ps
curl -sf "http://<internal-runtime-redacted>:${PM_BACKEND_HOST_PORT:-18081}/readyz"
bash scripts/verify_runtime_materialization_drift.sh

Verify after fix:

curl -sf "http://<internal-runtime-redacted>:${PM_BACKEND_HOST_PORT:-18081}/readyz"
curl -sf "http://<internal-runtime-redacted>:${PM_BACKEND_HOST_PORT:-18081}/contractz"

Fabric Contract Drift​

Symptoms:

  • Fabric presence or compatibility routes degrade
  • consumer publication checks fail

Run this check:

bash scripts/fabric-selfcheck.sh
python scripts/verify_oss_inventory_version_truth.py --strict

Verify after fix:

curl -sf http://<internal-runtime-redacted>:18081/fabric-presencez
curl -sf http://<internal-runtime-redacted>:18081/fabric-compatibilityz

Plane / Provider / Auth Integration Drift​

Symptoms:

  • sync endpoints fail
  • auth callback posture is wrong
  • planning or delivery projections are stale

Run this check:

python -m pytest -q backend/tests/test_settings_regression.py backend/tests/test_oidc_keycloak.py

Then inspect:

  • Plane Integration (docs/PLANE_INTEGRATION.md)
  • Provider OAuth And SSO Setup (docs/PROVIDER_OAUTH_AND_SSO_SETUP.md)
  • OIDC Session Contract (docs/OIDC_SESSION_CONTRACT.md)

Recovery Guidance​

If runtime or state repair becomes risky, switch to:

  • Recovery Runbook (docs/RECOVERY_RUNBOOK.md)

That document carries the backup, restore, and post-change verification posture.

License: AGPLv3

Helpifyr: https://helpifyr.com