Reference
Troubleshooting
Symptom-led recovery for the public site, private checkout, dependencies, Microsoft NT, Linux, WSLg, AI availability, and application development.
Start with the symptom you can actually observe. Do not stack speculative fixes: verify the expected result, reproduce the discrepancy, preserve useful evidence, isolate one cause, make the smallest repair, and rerun the original case.
Public documentation site
| Symptom | What to check | Recovery |
|---|---|---|
| A page or image does not open | Confirm the address belongs to the published documentation catalog rather than the private repository. | Return to Docs search. If the page is named as private, read Repository and download access. |
| Search returns no result | Try a product term, application name, platform, or task rather than a repository filename. | Browse by section or open the glossary. |
| The assistant is unavailable | GitHub Pages has no hidden Arcane AI credential or native host bridge. | Use local documentation search. Assistant availability requires a compatible trusted Arcane host. |
| A theme looks wrong | The site follows the selected Arcane appearance and can also follow the system preference. | Select Auto, Light, or Dark again; then reload. A custom skin remains local to the compatible Arcane environment that supplied it. |
| The generated catalog fails to load | A deployment may be incomplete or stale. | Reload once. If the failure persists, use the site's recovery links and report the exact page address and visible message. |
Checkout and dependencies
| Symptom | Likely boundary | Recovery |
|---|---|---|
| Clone reports not found or permission denied | The repository is private or your Git identity lacks access. | Follow Repository and download access; do not search for unofficial archives. |
| Large runtime files contain Git LFS pointer text | Git LFS is missing or the required objects were not hydrated. | Install Git LFS, run the documented git lfs pull include set, then git lfs fsck. |
| Dependency verification rejects a registry or lock | The checkout does not match the approved public dependency policy. | Restore the committed lockfiles and use npm ci; do not substitute a private or local registry. |
| A development check fails | The first nonzero result is the useful failure boundary. | Run the closest focused test, fix that cause, then rerun npm run check. |
Microsoft NT development
| Symptom | What it means | Recovery |
|---|---|---|
| A local development certificate prompt appears | The supported bootstrap is establishing current-user development trust. | Review the prompt and continue only for the checkout and user you intended. It is not production signing. |
| Shell reports the current Microsoft NT account | Direct launch uses the already-authenticated host identity. | This is expected. Use the provisioning walkthrough only when the first-user journey is actually in scope. |
| Closing the Shell seems different from Log out | Log out requests a real host-session logout. | Close the window for development and screenshots; do not select Log out merely to exit a demo. |
Linux and WSLg development
| Symptom | What it means | Recovery |
|---|---|---|
| Provisioner cannot install or change accounts | The process is not the separately authorized, already-root Provisioner, or the release did not verify. | Follow the exact root launch and unsigned-local verification steps in the Linux host guide. |
The taskbar shows [WARN:COPY MODE] and no window renders |
WSLg started without its normal graphics-redirection path. | Save work in every WSL distribution, close WSL GUI apps, run wsl --shutdown from Microsoft NT, then reopen Ubuntu. |
Ollama reports connection refused at 127.0.0.1:11434 |
No reachable Linux Ollama service is listening inside the distribution. | Check the installed executable and service state. Microsoft NT-host Ollama does not automatically satisfy the Linux check. |
| Direct Shell launch works but sign-in was not tested | Direct launch and first-login acceptance are different journeys. | Record only the journey actually exercised; use the provisioning guide for account staging and sign-in. |
Application development
- If a component does not become ready, verify both import completion and its documented ready event/state.
- If a browser package omits a file, add only the required path to the application's positive include inventory.
- If a native API call is denied, verify the application identity, host support, method contract, and declared capability. Do not widen permissions as a diagnostic shortcut.
- If a theme override works in one mode only, replace hard-coded values with Arcane tokens and verify Auto, Light, Dark, and saved appearance states.
- If Markdown or external content does not render, preserve the sanitizer and navigation boundary; do not enable arbitrary HTML or scripts to make one document work.
For the full evidence process, read the Debugging SOP.
When asking for help
Include the platform, exact development commit, command or page address, expected result, observed result, first error, and the smallest reproducible case. Remove credentials, protected data, usernames, hostnames, and unrelated logs.