> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
For device-side issues such as glove connection, tactile and EMF data anomalies, see [Wuji Glove Troubleshooting](/en/docs/wuji-glove/troubleshooting). For SDK-related issues, see [Wuji SDK Troubleshooting](/en/docs/wuji-sdk/troubleshooting).
## Won't start / white screen or crash
1. Confirm your OS meets requirements (Ubuntu 22.04 LTS or later)
2. Update GPU drivers to the latest version
3. Install WebKitGTK:
```bash theme={null}
sudo apt install libwebkit2gtk-4.1-0
```
4. Delete the application data directory and retry:
```bash theme={null}
# Back up first
cp -r ~/.wuji/studio/data ~/.wuji/studio/data.backup.$(date +%Y%m%d%H%M%S)
rm -rf ~/.wuji/studio/data
```
5. If it still won't start, check your system proxy. A proxy that intercepts WebView local resource loading causes a blank screen. Launch with proxy environment variables temporarily cleared:
```bash theme={null}
env -u http_proxy -u https_proxy -u all_proxy -u ftp_proxy -u no_proxy \
-u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY -u FTP_PROXY -u NO_PROXY \
GSETTINGS_BACKEND=memory \
wuji-studio
```
## Panels show blank
* Confirm a device is connected and you're in the Visualization View
* Check if the panel is subscribed to the correct Topic
* Try resetting the panel layout (right-click a preset tab → **Reset to Default**)
## Restore the default layout
To restore the default layout after changing it, right-click the current preset tab in the preset bar at the top (**Tactile Monitor** in the image below) and select **Reset to Default**. See [Layout Presets](/en/docs/wuji-studio/visualization/layout-presets) for more preset operations.
## Tactile matrix heatmap shows all black
* Confirm you're subscribed to the correct Topic (tactile or tactile\_zones)
* Check if the Matrix panel data range is set correctly (default 0.0\~1.0)
* Press the glove surface lightly and observe if data changes
## Tactile matrix heatmap is misaligned or sheared
* Check that **Columns** in the Matrix panel settings is 31: the tactile matrix is 24×31, and a mismatched column count shifts each row by one cell, shearing the whole heatmap
* Set Columns back to 31 in the Sidebar's **Panel** settings, or right-click the preset tab and select **Reset to Default**
## Firmware upgrade failed
1. Ensure stable power supply — do not disconnect during upgrade
2. Ensure stable network connection — use wired connection
3. The glove has a built-in rollback mechanism that automatically restores the previous version on failure
4. Wait for the glove LED to indicate rollback completion, then retry
## Encountering errors during upgrade
| Error Type | Description | Suggestion |
| - | - | - |
| Network Error | Cannot connect to firmware server | Check network connection |
| Server Error | Firmware server returned an error | Try again later |
| Config Error | Firmware server URL not configured | Contact administrator |
| Device Offline | Device disconnected during upgrade | Check cables and power supply |
## Use local firmware for upgrade
In Step 2, click the **Upload local file** button to select a firmware file (.zip format). After upload, the app automatically parses and displays the firmware version, release date, and release notes.
Using unofficial firmware may cause device damage or performance issues and may void the warranty.
Only use firmware files from trusted sources.
## Get technical support
Contact [support@wuji.tech](mailto:support@wuji.tech) with the following information:
* Device serial number (SN)
* Firmware version
* Wuji SDK / Wuji Studio version
* Operating system and version
* Steps to reproduce the issue
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.