27. Troubleshooting and FAQ

27.1 Launch

• App won't launch: check logs first (Settings → About → Open log directory); or uninstall and re-install.
• Blank window after launch: usually the system's WebView component is too old; see Chapter 2.

27.2 Sign-in

• SSO browser bounces back but the app doesn't react: usually a browser proxy / VPN blocked the local callback port; turn off the proxy and try again.
• No models after sign-in: Settings → Models → Refresh, or sign out and back in.

27.3 Sessions

• Session unresponsive: click the Stop button, then send a new message.
• History looks truncated: probably triggered compaction; click the summary to expand.
• "Service not ready": wait 30 s; if it persists, open Settings → Hooks → Error Drawer for the specific reason.

27.4 Tools

• A tool call spins forever: probably a background task scheduled by the model but never tailed; open the task card to see the live log.
• A tool was denied: check the permission setting for the tool in the current mode in the agent manager → "Configure tools".
• External service unreachable: check endpoint and credential; the error drawer carries the raw server response.

27.5 Security analysis

• YARA scan empty: the default install may not ship the full ruleset; ask your internal channel.
• Decompilation is slow: it calls the model; complex samples can take tens of seconds. You can let the assistant push it to background.

27.6 Companion messaging

• No reaction after WeChat QR scan: the channel takes up to 30 s to initialise; refresh the QR code and retry.
• Pairing code failed: 10-minute TTL — regenerate.
• Approval card didn't show in WeChat: check whether the channel is still online (Settings shows connection status).

27.7 Performance

• High CPU: if you enabled many background tasks, mind the cap; see the running list in Settings → Hooks.
• Disk usage growing: usually session history or samples directory; see the size in Settings → Data → Data directory and archive old sessions as needed.

27.7.1 Precise model-error categorisation

Server-side errors are now categorised precisely — tips tell you exactly what to do, not a generic or misleading message:

Sending with no configured model no longer hangs: if you deleted the model provider you were using and then send, it used to hang; now it does an inline confirmation in the message stream guiding you to switch to an available model. A startup failure also resets the run state, so it no longer stays stuck on "running".

27.7.2 macOS App Translocation upgrade failure

If you didn't drag the app to Applications and run it from "Downloads" or "Desktop", clicking "Check for updates" is blocked by macOS's App Translocation (the app runs from a read-only temporary image). This release detects that "read-only location" and fails fast with a clear instruction:

"Quit the app → drag it to the Applications folder → reopen → check for updates again"

Other read-only volume / managed-directory failures get the same friendly message.

27.7.2.5 Windows background-process stability

The background services (zWorkspace / zMCP) on Windows have been systematically hardened:

• Process liveness probing now uses system-level handle wait — no more mistaking a live child as exited. (mac / Linux behaviour unchanged.) Fixes "each workspace re-open spawns another one; the old becomes an orphan."
• GUI subprocess stderr capture is fixed; the "raw error" in startup diagnostic reports comes back with content, so the root cause is identified more accurately.
• MCP config read/write no longer drops fields: previously adding / removing / toggling an MCP backend in "Configure Tools" could silently wipe other stdio backends' launch commands, taking down zMCP entirely "missing command" next time.
• One bad backend no longer takes down the gateway: with a malformed / unreachable / disabled backend, zMCP still starts; the bad one is skipped with a warning, the rest stay usable.
• Backend connect is async + bounded retry: after a reboot or when the network isn't ready, a slow / unreachable backend no longer blocks gateway startup; backends probe concurrently in the background with bounded retries and reconnect automatically once the network comes up. Fixes "after rebooting, one unreachable remote / LAN backend takes down the whole tool gateway — all tools unusable".
• App-exit cleanup: OS-level process-group binding now cleans up the whole process tree when the app crashes / is force-killed / upgrades; child processes also use a more reliable parent-exit listener, so no orphans are left behind.
• zAgent crash logs preserved in full: when the background conversation process (zAgent) crashes unexpectedly, the native exception is captured and the pre-crash stderr is preserved in full — no more silent exits (the dreaded "exit code 2" type failures). With complete logs, root-cause is much faster. When writing the persona or feeding data to a sub-agent hits a broken pipe, it now reports zAgent's real exit reason instead of a generic symptom message.

27.7.2.6 Trial / licence expiry lock can quit the app

The full-screen lock for trial / licence expiry now has a persistent "Quit" button at the bottom — previously clicking close only hid to the tray (equivalent to not quitting); now you can cleanly terminate the process from any state. The website / homepage link in the lock is avlcode.cn.

27.7.3 Auto-diagnostics for background-workspace startup failure

If the background workspace service (zMCP) fails to start, AVL Code auto-collects diagnostics on the local machine (self-connect port comparison, process liveness probing, etc.) and posts a root-cause conclusion + recommended action directly in the error drawer — no manual steps required.

• A diagnostic report file is written to disk (the latest 20 are kept).
• Zero action required; no data is sent anywhere.
• "zWorkspace / zAgent binary not found" surfaces the root cause: if the built-in zWorkspace / zAgent component can't be located at startup, instead of just "binary not found" it now reports the real reason the embedded component failed to unpack, with platform-specific troubleshooting tips. (Related: the embedded-component unpack cap was raised from 64 MiB to 256 MiB, fixing startup failures on some Intel machines where a grown component was wrongly blocked by the safety guard.)
• The diagnostic report can be one-click-attached to a Feedback submission to help us investigate.

27.7.4 Online docs

When you need docs:

• Sidebar Help button: opens avlcode.cn/docs.html in your default browser.
• macOS Help menu → Online Docs: same destination, sitting right after "Command list".

27.8 Logs

The log directory is one click away in Settings → About → Open log directory. Crash stacks also appear in the error drawer — no terminal needed.