27. Troubleshooting and FAQ

27.1 Launch

App won't launch: check logs first (Settings → Data → Open log directory); or uninstall and re-install.
Blank window after launch: usually the system's WebView component is too old; see Chapter 2.
Black screen with the Linux package: the Linux DEB packages now adapt to the system WebKit automatically — when the system already has WebKit 4.1 (e.g. Kali / Debian / Ubuntu), the system's own component and hardware acceleration are preferred, with no more forced software rendering (which used to cause a black screen on Kali and similar systems); when it isn't installed (e.g. Kylin V11, offline environments), the bundled component is used automatically with compatibility rendering enabled, so it works out of the box.
Windows says a project is "Locked by BitLocker" / "Drive not ready" when opening it: when the drive holding the project is BitLocker-locked, one click on "Locked by BitLocker" brings up the system unlock dialog, and the project opens automatically once unlocked; for "Drive not ready", check the drive first (e.g. whether the external drive is connected) and try again.

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 → Model settings → 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.
Binding 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:

HTTP	Meaning	Tip
402	Insufficient points	"Insufficient points; buy coupons" (coupon wording, consistent with the account usage display and server-side billing — no longer "top up / reset / balance"; no longer retried as a transient error)
429	Plan request-rate limit / period quota exhausted	Respect the server’s retry delay without retrying early, with a cumulative wait limit per turn; notices distinguish requests-per-minute limits from period quota and show server-reported period and usage
401 / 403	Auth failed / sign-in needed	"Sign in again or replace your key" (no longer pointing at config)
—	Input over token cap	Categorised as "context too long" with an accurate message
503	No channel currently available for this model	"Retry later or switch model"
502 / 529 / overloaded	Upstream error / busy	Congestion shows a reason and countdown, with controls to switch models or stop waiting; authentication, account balance and quota shortages are reported separately rather than repeatedly retried as temporary congestion
404	Endpoint not found	A new `endpoint_not_found_error` category; tip says "Check the Provider Base URL" (kept distinct from "model not found in API JSON")

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 subagent 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

Alpha (preview) builds are valid for 45 days (counted from that build's release; checked at launch and hourly thereafter). Once expired, a full-screen lock appears and you need to upgrade to a newer build to keep using the app: if you're signed in and have usage available, it checks for updates, downloads and restarts after a countdown automatically; if you're not signed in it offers "Sign in"; with no usage available it offers "Buy vouchers" and "Upgrade plan".

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 → Data → Open log directory. Crash stacks also appear in the error drawer — no terminal needed.