Skip to main content

Troubleshooting

> Release admission classification: internal_only_excluded

Use this page as the short-entry runbook. Deeper operator procedures remain in the existing runbooks and product docs.

Reader Outcome​

This page should let an operator quickly classify whether the problem is primarily:

  • Spindle runtime/materialization drift
  • MCP gateway or auth drift
  • callback/approval/dispatch drift
  • support-lane drift
  • release/metadata/docs drift

If the failure belongs to a foreign owner after the first bounded Spindle check, gather evidence here and hand off instead of inventing a local workaround.

Primary References​

Runtime / Compose / Drift Problems​

Run this check:

python infra/scripts/verify_stack_contract.py --check-running
python infra/scripts/verify_runtime_materialization.py --output artifacts/evidence/runtime-materialization.json
python infra/scripts/verify_accounting_workspace_setup.py --ssh-target <internal-runtime-redacted><internal-runtime-redacted> --expected-company HERP --expected-country Germany
python maintenance/verify_oss_inventory_version_truth.py --check-live --ssh-target <internal-runtime-redacted><internal-runtime-redacted> --output artifacts/evidence/oss-version-truth.live.json

If the Accounting workspace crashes on Payment Entry Number Cards:

  1. run the accounting workspace verifier above
  2. if payment_entry_table_present=false, rerun the canonical bootstrap/migrate path:
    • bash infra/scripts/bootstrap-site.sh
  3. if the verifier still shows Payment Entry DocType truth but the table is unreadable or missing, run the repo-owned ghost-table repair path:
    • python infra/scripts/repair_payment_entry_ghost_table.py --ssh-target <internal-runtime-redacted><internal-runtime-redacted>
  4. if the schema is green but the HERP Germany demo company is still missing, apply:
    • bash infra/scripts/apply-tenant-setup.sh infra/tenant-setup/herp-de-sandbox.json

First handoff clue:

  • if compose/runtime truth is clean but the shared-host authority or foreign callback lane is still broken, classify as external owner follow-up instead of changing Spindle business truth locally

MCP / Operator Gateway Problems​

Run this check:

python infra/scripts/verify_authenticated_mcp_demo_action.py --ssh-target <internal-runtime-redacted><internal-runtime-redacted> --host-repo-path /home/administrator/jhf-spindle --output artifacts/evidence/mcp-authenticated-demo-action-live.json
python infra/scripts/mcp-call.py --help

Callback / Approval / Dispatch Problems​

Run this check:

python infra/scripts/check_callback_transport.py --output artifacts/callback-transport.json
bash infra/scripts/contract-smoke.sh
python -m pytest -q apps/jhf_spindle_core/tests/test_approval_packets.py apps/jhf_spindle_core/tests/test_document_dispatch.py

Support / Zammad Problems​

Run this check:

bash infra/scripts/zammad-smoke.sh
python infra/scripts/run_zammad_erp_corner_cases.py
python infra/scripts/support_case_smoke.py

Release / Contract Drift Problems​

Run this check:

python infra/scripts/check_markdown_compliance.py
python infra/scripts/check_compatibility_contracts.py --check
python infra/scripts/export_fabric_metadata.py --check
python infra/scripts/openclaw_plus_acceptance.py

Public-docs/source-truth check:

python infra/scripts/check_markdown_compliance.py
python infra/scripts/check_compatibility_contracts.py --check
python infra/scripts/export_fabric_metadata.py --check

License notice: AGPLv3 (GNU Affero General Public License v3.0) Website: https://helpifyr.com