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: establish the expected result, preserve the discrepancy, isolate one cause, and make the smallest repair. Run a reproduction or check only when the user explicitly requests it.
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 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, verify the intended repository owner and authenticated route, and report the exact access failure. |
| Large runtime files contain Git LFS pointer text | Git LFS is missing or the required objects were not hydrated. | Install Git LFS and run the documented git lfs pull include set. |
| Dependency installation reports a registry or lock problem | The checkout or configured registry does not match the declared dependency inputs. | Restore the committed lockfiles and use the repository's selected install path. |
| An explicitly requested development check fails | The first nonzero result identifies the failing operation. | Inspect that cause and rerun only if the user explicitly requests another check. |
Microsoft NT development
| Symptom | What it means | Recovery |
|---|---|---|
| A local development certificate prompt appears | The bootstrap is creating the current user's Microsoft NT development signing identity. | 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. | Follow the root launch 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, inspect both import completion and its documented ready event/state.
- If a browser package omits a file, add the required path to the application's declared package contents.
- If a native API call is denied, inspect the application identity, host support, method contract, and declared capability. Do not alter operating-system permissions as a diagnostic shortcut.
- If a theme override works in one mode only, replace hard-coded values with Arcane tokens and preserve Auto, Light, Dark, and saved appearance states.
- If Markdown or external content does not render, identify the first renderer or protocol failure. Reject genuinely malformed or executable input at that exact rendering boundary and preserve unavoidable browser-protocol behavior. Any broader sanitizer, navigation restriction, or hardening policy requires exact user authorization for that control and scope.
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.