Zum Hauptinhalt springen

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​