Troubleshooting

Troubleshooting — symptoms, causes and fixes

Outcome: Identify the failure point, avoid destructive workarounds and collect enough non-secret evidence to report an issue. Start with the local status console, then the Panel's Diagnostics, Logs, Crashes and hardware/capability views once enrollment is complete.

Boot, firmware and installation

Symptom	Likely cause / what to check	Safe recovery
USB drive is not listed as a boot option	USB writer selected wrong device, firmware is not starting the UEFI entry, or image is corrupt.	Recheck archive checksum, reflash the correct removable drive and choose its UEFI boot entry. Avoid writing the internal disk.
`dd` finished but stick will not boot	Pipeline decompression failed, incomplete write or wrong destination.	Recheck `.img.xz.sha256`; repeat the pipefail-protected procedure after verifying the device.
Secure Boot rejects both entries	Development owner certificate not present in firmware `db`, different signing key, or a tampered image.	Verify exact image/checksum and append the matching `OWNER.DER`/`.esl`; do not replace factory keys. Refuse to use a checksum-mismatched image.
Secure Boot menu offers only reset/delete keys	Firmware cannot append a certificate through that UI, or an administrator has locked key management.	Stop. Do not clear existing platform or Microsoft keys. Use firmware with supported append, consult its administrator, or use a non-Secure-Boot test environment under your policy.
Windows asks for its recovery key after enrollment	Firmware trust database change triggered disk encryption recovery.	Retrieve the saved recovery key; resume protection afterward. Do not alter disks, reinstall Windows or clear Secure Boot keys to bypass recovery.
LexiKernel refuses boot because IOMMU is absent	Intel VT-d / AMD-Vi not enabled or not functional.	Enable the supported IOMMU mode in firmware, or boot the Linux 7.4-rc1 entry. Do not bypass DMA isolation.
LexiKernel boots but cannot get network link	Unsupported NIC or revision, unplugged cable, or driver initialization mismatch.	Verify link and model/revision against Hardware. Boot Linux entry for a wider set of drivers; include NIC details in a report.
No available Panel address on console	Network did not configure, service did not start, or boot incomplete.	Read local boot/status messages, verify physical link and DHCP, and use Diagnostics if accessible. Do not invent an address or assume another port.
USB data partition seems smaller than the stick	First-boot expansion is incomplete or usage reporting is unavailable (especially under LexiKernel).	Allow first boot to complete. Compare capacity using the Linux entry; missing LexiKernel storage metrics are a known gap. Do not repartition live evidence media impulsively.
Secure Boot status displays development signing	Expected development signing, not a production certificate.	Read Security; do not present development-signed media as production-qualified.

"LEXIKERNEL STOPPED" on a blue page

The large text names the stage and the reason. Smaller yellow lines underneath, when present, are the diagnosis: LK:USB:INITIAL_SCAN_ERROR lines describe each USB controller that failed (its status registers and connected ports), and LK:IOMMU:AMD-VI lines report what the IOMMU refused. Photograph the whole page and include it in a report. The Linux entry (2) still boots on the same stick.

First boot, account and Panel

Symptom	Likely cause / what to check	Safe recovery
No setup code field appears	Expected default: the owner has not enabled setup-code gating.	Immediately enroll on a controlled LAN. Do not publish an unclaimed setup page on an untrusted network.
Setup form requires a code not known to the browser user	Code gating is enabled, and the code is presented on local console/installer.	Obtain it from the device operator; do not guess, bypass or share it in support logs.
Setup reports password validation failure	Root/admin confirmation mismatch or administrator password fails length/complexity.	Use the exact form labels: root 12+ characters; admin 12+ with uppercase, lowercase and a digit; match confirmation values.
Setup page is visible to an unexpected visitor	Unenrolled Panel reachable from a shared network.	Isolate the device, have the legitimate operator complete enrollment before reconnecting, and assess whether another account was already created.
Browser cannot open the Panel	Wrong displayed address, network isolation, firewall or incomplete enrollment.	Read the console's address and setup state; appliance Panel uses port 8090. Developer installs have different defaults.
Native page says unavailable with a reason	Feature depends on Linux services or an unsupported LexiKernel capability.	Keep the reported reason and switch to Linux if the operation is required. Do not mistake the refusal for a successful action.
Browser freezes just after LexiKernel console	Known intermittent LexiKernel browser-boot freeze (1 of 5 in the supplied status).	Record boot kernel and logs, retry via Linux for functional work, report reproducible diagnostics; there is no confirmed root-cause fix yet.
A Panel operation fails but no detailed toast appears	API, permission or service failure recorded in the failed-request log.	Collect Diagnostics → debug kit and Logs, scrub for secrets before transfer; do not assume an unreported mutation succeeded.
Cannot open an admin-only feature	Session has insufficient role, or privileged route rejected the request.	Ask an authorized administrator to grant the required role. Never bypass controls with a direct API call.

Models, performance and updates

Symptom	Likely cause / what to check	Safe recovery
No models to select	Development image ships without model weights.	Use Models to download, upload or import a model; verify its integrity before serving.
Verified-only import refuses a model	Model SHA-256 missing, incorrect or admission policy does not accept the artifact.	Recalculate and compare its real digest; use a trusted, complete model. Do not disable verification solely to conceal a mismatch.
Instance fails to start	Missing engine runtime/library, invalid flags, model/device mismatch or insufficient memory.	Review explicit launch error, Builds and Engines, model metadata and Fit Lab; don't invent extra flags.
GPU unavailable on LexiKernel	Native RDNA3 hardware path remains unqualified; a Linux driver-domain guest is used for GPU work.	Use Linux 7.4 on the USB, or record a kernel capability refusal; no native LexiKernel Vulkan guarantee exists yet.
Slow CPU inference under LexiKernel	Current per-process threads are constrained to one CPU.	Run comparable workloads under Linux; benchmark each environment independently.
GPU/CPU power or storage counter is blank	Telemetry not implemented for that kernel/device.	Read capability status; do not report blank as zero. Use Linux where supported.
Faster engine result cannot be reproduced	Different image/kernel, model quant, MTP, power cap, KV cache, context, temperature or insufficient repeats.	Follow the full benchmark protocol, including fresh random prefixes, three runs and honest one-run long-context labels.
TLS download fails on older endpoint	Native runtime deliberately rejects older TLS, TLS 1.2 without extended master secret or unsupported certificate/private-key options.	Use a supported, certificate-verifying TLS endpoint; do not disable verification.
An update or rollback is refused	Signature/rollback validation, inconsistent backup or failed preflight.	Preserve signed evidence, use Storage, Backup and Updates to inspect/restore a verified backup; never overwrite rollback evidence by force.

Reporting a reproducible problem

Record image identity (the <id> in the image file name), boot choice, observed signing state, device model/revision, engine/model quantization, exact error text, successful/failed steps and whether the behavior repeats. Capture local logs and a diagnostic bundle through Diagnostics. Remove secrets and personal data before sharing: passwords, enrollment codes, API tokens, private model prompts and unrelated files. Hardware qualification requires real-device evidence; virtual-machine results cannot be described as physical runs.