Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

Use this page as the short-entry runbook. Deep product-specific flows remain in the existing docs and runbooks.

Primary References​

  • Operations
  • Stack Contract (docs/STACK_CONTRACT.md)
  • Host Docker Log Guardrails (docs/HOST_DOCKER_LOG_GUARDRAILS.md)
  • OIDC Surfaces and Bootstraps (docs/OIDC_SURFACES_AND_BOOTSTRAPS.md)
  • Agent Reconcile and GC (docs/AGENT_RECONCILE_AND_GC.md)

Baseline Runtime Problems​

Run this check:

python scripts/validate-baseline-stack-matrix.py
python scripts/verify-runtime-guardrails-v1.py
python scripts/verify-runtime-guardrails-v1.py --live-host <internal-runtime-redacted> --ssh-user administrator --remote-repo-path /home/administrator/jhf-heddle

Runtime / Materialization / Drift Problems​

Run this check:

python scripts/verify-runtime-materialization-drift.py
python scripts/verify-runtime-materialization-drift.py --live-host <internal-runtime-redacted> --ssh-user administrator --remote-repo-path /home/administrator/jhf-heddle

Fabric Consumer / Claim Drift​

Run this check:

python scripts/validate-fabric-consumer-failclosed-matrix.py
python scripts/validate-identity-claim-vocabulary.py --contract config/identity/claim-vocabulary.v2.yaml
python scripts/validate-stackwide-claim-session-core.py --contract config/identity/stackwide-claim-session-core.v1.yaml

Plane / Loom OIDC Bridge Problems​

Run this check:

python scripts/validate-plane-oidc-runtime.py --base-url https://<internal-runtime-redacted> --insecure
python scripts/validate-loom-oidc-runtime.py --base-url https://<internal-runtime-redacted> --insecure
python scripts/verify-plane-oidc-callback-smoke.py
python scripts/verify-loom-oidc-e2e.py

Agent Reconcile API / Worker Problems​

Run this check:

python scripts/validate-agent-reconcile-api.py
python scripts/validate-agent-reconcile-policy.py
python -m unittest tests.test_agent_reconcile_api tests.test_agent_reconcile_worker

Every runtime- or troubleshooting-path above is intended to be execution-link-ready and repeatable without inventing local shadow truth.

License: AGPLv3
Project: https://helpifyr.com