Skip to main content

Debug Fabric readiness issue

Use this page when Fabric readiness is unhealthy or inconsistent with what operators believe the stack is doing.

When to use this page​

  • Readiness is red or contradictory.
  • API-level posture and runtime behavior disagree.
  • You need to determine whether the issue is Fabric itself, runtime materialization, or a downstream provider boundary.

Prerequisites​

  • You can access Fabric health, services, and readiness routes.
  • You can compare runtime materialization before redeploying anything.

Architecture / Flow​

Step-by-step procedure​

1. Establish the Fabric-owned posture​

Use:

GET /health
GET /api/v1/platform/services
GET /api/v1/observability/readiness

2. Compare runtime materialization when posture is inconsistent​

Use:

python ./scripts/verify_runtime_materialization.py --check

3. Confirm guardrails before redeploy or host mutation​

Use:

bash ./scripts/verify-runtime-guardrails.sh

4. Narrow the boundary before escalating​

Decide whether the mismatch lives in:

  • Fabric API truth
  • runtime materialization
  • provider dependency outside the API surface itself

5. Re-verify with the same evidence family​

After a bounded fix, re-run the same health, services, and readiness checks and confirm one representative downstream Fabric consumer path.

Verification​

This runbook is being used correctly when:

  1. API truth and runtime materialization are compared before redeploy
  2. the failure boundary is narrowed before escalation
  3. post-fix verification uses the same readiness surfaces that exposed the problem

Common failure modes​

Treating every readiness issue as a redeploy problem​

Problem:

  • provider or materialization issues get hidden under noisy recovery.

Better path:

  • separate API truth, runtime materialization, and provider boundaries first

Verifying only one green surface after the fix​

Problem:

  • the readiness symptom disappears in one place but persists elsewhere.

Better path:

  • repeat the same full evidence family and confirm one downstream consumer path

Source Truth​

  • contracts/docs/public_manufacturer_docs_post_v1_runbooks_v1.json
  • JaddaHelpifyr/helpifyr-fabric:docs/TROUBLESHOOTING.md
  • JaddaHelpifyr/helpifyr-fabric:docs/operations/HOST_STACK_VERIFICATION.md
  • JaddaHelpifyr/helpifyr-fabric:docs/operations/OPENCLAW_PROVIDER_VERIFICATION.md

Next paths​