After reading this page you will be able to: work through common symptoms, collect useful details, and find the next support step.
- Restart the app.
- Click Check token in Settings -> Required Setup.
- Check the network, proxy, firewall, and local ports.
- Check for updates in Settings -> About.
- Open Settings -> System -> Log Directory, use the displayed path and the folder button to locate or select the directory, then collect logs and record the version, operating system, and reproduction steps.
For each scenario below, do the table check first, then follow the steps.
| Symptom | First check |
|---|
| Startup screen hangs, the window is blank, or the app does not respond | Look for leftover AIPC UP processes and startup errors in the log |
- End leftover AIPC UP processes and start the app again.
- Confirm the configured work and log directories exist and are accessible.
- If the log points to GPU or rendering issues, update the graphics driver and try disabling hardware acceleration.
- Submit a diagnostic report with the exact error if it still fails.
| Symptom | First check |
|---|
| “Check token” fails, the token is invalid, or HuiAI cannot be reached | Token completeness and access to HuiAI services |
- Re-paste the token in Settings -> Required Setup without leading or trailing spaces.
- Confirm it has not been revoked and that account resources are available.
- Check the proxy, firewall, and system clock.
- Save the token and run the check again.
| Symptom | First check |
|---|
| 401, authentication failure, timeout, or no response after sending | Selected model, API key, Base URL, and provider status |
- Confirm the intended model is selected in Settings -> Models.
- Check the key, Base URL, and model name. A HuiAI token is not a model API key.
- Check provider quota, regional restrictions, and proxy settings.
- Retry with a short message and record the response status.
| Symptom | First check |
|---|
| An Agent cannot run, reports that you are signed out, or fails to start | Required Setup status and the repair page |
- Sign in, then check the token again.
- Open the Agent repair page and complete its dependency instructions.
- Close and reopen the current session.
- For migration or incomplete-installation errors, update or reinstall the latest build and keep the logs.
| Symptom | First check |
|---|
| Clicking the microphone produces no transcription or says setup is missing | Microphone permission, HuiAI token, and network |
- Allow AIPC UP to use the microphone in system privacy settings.
- Check the token and confirm voice resources are available.
- Close other apps using the microphone and retry.
- Check the input device and network, and record recognition-service errors.
| Symptom | First check |
|---|
| The floating-window control is clicked but no window is visible | Other display edges, the taskbar, and windows positioned off-screen |
- Check the taskbar area and every connected display.
- Toggle the floating-window control again.
- Disconnect an external display and restart the app.
- Record the display layout and app version if it remains missing.
| Symptom | First check |
|---|
| The file manager is read-only and cannot write | Directory permissions, filesystem mount state, and workspace status |
- Confirm the directory exists and the current user can write to it.
- Check disk space and whether the filesystem is mounted read-only.
- Switch to a known writable directory to identify the scope.
- Confirm permissions in the operating system file manager, then reopen the project.
| Symptom | First check |
|---|
| Browser automation cannot connect to Chrome | Chrome remote debugging and the debugging port |
- Open Chrome and visit
chrome://inspect/#remote-debugging.
- Follow Chrome’s instructions to enable remote debugging and open the target page.
- Check the AIPC UP browser settings and ensure the port is not in use.
- Run connection detection again, then test with a low-risk action.
| Symptom | First check |
|---|
Windows desktop control reports that client.exe is not running | Whether client.exe exists and the local service port is available |
- Confirm Windows is the current operating system and check whether security software quarantined the helper.
- Confirm
client.exe is running in Task Manager.
- Check that the local service port is not used by another process.
- Restart AIPC UP and run a low-risk diagnostic.
| Symptom | First check |
|---|
| A WebUI page will not open on the LAN or through the public tunnel | Port, firewall, tunnel state, and public quota |
- For LAN access, put both devices on the same network and check port
25808.
- Allow the app’s local port through the firewall.
- For public access, restart the tunnel and confirm its quota is available.
- Do not publish the public URL. Record the network and error page if it still fails.
| Symptom | First check |
|---|
| A configured bot does not receive or reply to messages | Pairing approval, credential expiry, and bot permissions |
- Confirm the credential is current and save the configuration again.
- Review and approve pending pairing requests.
- Confirm the bot can send messages in the target group or conversation.
- Send a short test and inspect the gateway log.
| Symptom | First check |
|---|
| Update checking, downloading, or installing fails | Network, disk space, app processes, and installer log |
- Retry and confirm the proxy or firewall allows the update server.
- Close the app and processes that may lock the install directory.
- Record the version, error text, and failed phase from the log.
- Download the official installer, run it manually, and check the version again.
The default log location varies by operating system and installation method. In Settings -> System -> Log Directory, use the path displayed by the app; click the folder button to locate or select the log directory, and restart when prompted after a change. After collecting the required logs, use Settings -> About -> Report a problem when available. Whether diagnostic events or log reports are sent depends on release configuration and trigger conditions; review the content before submitting. For further help, visit Contact and Support.
