Skip to main content

Troubleshooting

jhf-lantern Troubleshooting

Dependency Install Fails​

Use the wrapper so Node uses the local system CA posture without disabling TLS:

python scripts/run_pnpm.py install

Do not switch the repo to npm install or commit package-manager drift.

Likely owner: jhf-lantern

First checks:

  • python scripts/run_pnpm.py install
  • python scripts/verify_module_features.py

UI Does Not Start​

Run the fast checks first:

python scripts/verify_module_features.py
python scripts/run_pnpm.py typecheck
python scripts/run_pnpm.py build

If live mode fails, fall back to fixture mode to separate UI build problems from upstream readback problems.

Likely owner: jhf-lantern if fixture mode also fails; otherwise the upstream owner repo behind the missing surface

First checks:

  • python scripts/run_pnpm.py typecheck
  • python scripts/run_pnpm.py build
  • python scripts/run_pnpm.py test:smoke

Live Readback Is Unavailable​

Lantern should fail closed when upstream owner surfaces are missing. Expected states include future_contract, restricted, stale, and upstream_unavailable.

Likely owner: upstream owner repo, not Lantern, unless fixture mode or local BFF contracts are already broken

Evidence to collect:

  • the affected route
  • whether fixture mode still renders
  • the exact fail-closed state shown in the UI
  • the upstream endpoint or repo contract expected for that surface

Next action:

  • if fixture mode is healthy, route the problem to the owner repo for the missing upstream truth
  • if fixture mode is also broken, keep the investigation in jhf-lantern

Host Runtime Checks​

When runtime state matters, verify the real host first:

ssh <ssh-user>@<live-host>

Then inspect the owner-defined Lantern runtime and documented health endpoints from docs/DEPLOYMENT.md and docs/LIVE_VERIFY.md.

Likely owner: runtime owner for the affected host or deployed Lantern materializer

Verify after recovery:

  • the relevant upstream surface reads back again
  • Lantern returns to the expected read-only state
  • no local fallback or shadow truth was introduced to mask the upstream failure

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