Troubleshooting

Start with the splash screen. It is the production status surface.

No Node URL Appears

The splash moves through these states:

State	Meaning
starting LapEE...	Network has not produced a primary interface yet.
network up; starting HyperBEAM...	DHCP succeeded and init is starting HyperBEAM.
starting HyperBEAM... HOST (Ns)	HyperBEAM has not answered ~tpm@2.0a/info yet.
Running at http://HOST:8734/	Use this URL from the verifier machine.

If the URL never appears, check wired network first. For WiFi, confirm that wifi.conf was staged and accepted by the strict parser.

WiFi File Rejected

wifi.conf must contain exactly two lines:

SSID
WPA2-PSK

Rules enforced at boot:

• SSID length: 1 to 32 bytes.
• SSID characters: letters, digits, underscore, space, dot, apostrophe, dash.
• PSK length: 8 to 63 bytes.
• PSK characters: printable ASCII only.
• PSK must not contain ", \, $, or backtick.
• No NUL bytes or extra lines.

Use the helper when possible:

make wifi-creds

Verifier Cannot Reach The Node

Use the exact URL from the splash screen:

export LAPEE_URL=http://HOST:8734
curl -fsSL -H 'accept: application/json' \
  -H 'accept-bundle: true' \
  "$LAPEE_URL/~tpm@2.0a/info"

If that fails, the verifier is not reaching HyperBEAM. Check the local network, client isolation on the router, VPN routing, and host firewall rules.

Stale Capture Warning

scripts/interpret-local-capture.sh rejects file inputs older than 30 minutes unless LAPEE_ACCEPT_STALE=1 is set. Prefer the live network path:

./scripts/interpret-local-capture.sh \
  --url "$LAPEE_URL" \
  --label "operator-check"

Saved envelopes can describe an older boot. Do not use them for live acceptance unless that is intentional.

Secure Boot Fails

Check which trust path you intended:

• Release key enrolled.
• Exact UKI hash admitted.
• Operator db key enrolled and used to sign the local build.

Adding wifi.conf or config.json changes the disk image hash, but it does not change EFI/Boot/BootX64.efi.

Memory Encryption Halt

Production physical boots require Intel TME or AMD SME unless the image was built with the reduced memory-encryption gate:

make runtime-image TME=0

TME=0 is not a no-TPM build. It records LAPEE_NO_TME=1 in the measured kernel command line and still uses TPM-backed attestation.

TPM Evidence Fails

Read the verifier failure, not just the final verdict.

Common causes:

• EK chain cannot anchor to the root bundle.
• AK policy does not match PCRs 0,1,7,10,11,14,15.
• Quote nonce or pcrDigest mismatch.
• Runtime PCR 15 replay does not match the quoted value.
• PCR 15 does not commit to the reported node-message-id.
• The node is serving an old cached envelope while the verifier expected a fresh nonce-bound attestation.

For reviewer or CI checks, run the secondary verifier against the captured bundle:

python3 secondary-external-verifier/verifier_hb.py boot-attestation.json