14 FAQ & Troubleshooting

14.1 Connection Issues

SSH connection fails

Symptom: clicking Connect hangs for a long time or fails immediately.

Troubleshooting steps:

1. Network reachability: run ping <host> and ssh -v <user>@<host> in a local terminal to confirm the network and port are reachable.
2. Correct port: confirm the target SSH port (specify it in the session configuration when it is not the default 22).
3. Firewall: make sure neither the local nor the remote firewall blocks the port.
4. Connection timeout: increase the connection timeout in “Settings → Connection → Timeout” (default 30 seconds).
5. SSH keep-alive: if the connection drops frequently, set the SSH keep-alive interval in “Settings → Connection → Timeout” (default 60 seconds; 0 disables).

SSH authentication fails

Symptom: the authentication retry dialog appears.

Troubleshooting:

1. Wrong password: re-enter the correct password.
2. Key mismatch: confirm the selected private key matches a public key authorized on the server (the public key assistant can redeploy it).
3. Wrong key passphrase: enter the correct passphrase.
4. PAM keyboard-interactive: if the server uses PAM authentication (rejecting the plain password method), WxTerm automatically falls back to keyboard-interactive — no extra configuration needed.
5. Agent key not loaded: when authenticating via SSH Agent, confirm the agent has the corresponding private key loaded.

Backspace prints ^H instead of deleting

Cause: the backspace key mapping does not match the server’s shell.

Fix: switch “Backspace key mapping” in “Settings → Keyboard” to ^? (or the other way around).

Garbled Chinese text

Cause: the terminal encoding does not match the server’s locale.

Fix:

1. Check the server locale (echo $LANG).
2. Set “Encoding” in the session configuration or quick connect to the matching encoding (e.g. GBK).
3. The default UTF-8 works for most modern Linux systems.

Serial port cannot be opened

Troubleshooting:

1. Permissions: on Linux, serial devices usually require the user to be in the dialout group: sudo usermod -aG dialout $USER (log out and back in for it to take effect).
2. Device busy: make sure no other program (e.g. minicom) is holding the serial port.
3. Device path: confirm the device path (/dev/ttyUSB0 / /dev/ttyS0 / COM3, etc.).
4. Driver: USB-to-serial adapters need the corresponding driver (CH340/CP2102/FT232).

14.2 File Transfer Issues

SFTP transfer fails

Troubleshooting:

1. Confirm the SSH server has the SFTP subsystem enabled (a Subsystem sftp line in sshd_config).
2. Confirm the user has read/write permission on the target directory.
3. Check the error message of the failed task in the transfer queue.

Drag-and-drop transfer does not respond

Cause: the operating system does not support native drag-and-drop, or the SSH sidebar is not open.

Fix:

1. Confirm the active tab is an SSH session and the SSH sidebar file panel is open.
2. Native drag-and-drop may be limited under Linux Wayland; use menu “Tools → Upload/Download” instead.
3. Use the “Upload” button in the SSH sidebar file panel instead.

Zmodem transfer stuck

Troubleshooting:

1. Confirm lrzsz is installed on the remote (rz / sz commands).
2. Confirm rz (receive) or sz <file> (send) was run on the remote first, then trigger the matching direction in WxTerm.
3. For slow large transfers, check the serial baud rate or network bandwidth.

14.3 Display Issues

Terminal font displays incorrectly

Troubleshooting:

1. Confirm the font family is selected correctly in “Options → Font Size”.
2. CJK characters shown as boxes: check a Chinese font in the font family list as a fallback.
3. Font too small/large: adjust temporarily with Ctrl+= / Ctrl+-, or change the base size in the font settings.

Remote desktop shows only part of the screen

Cause: the remote desktop image does not match the window size.

Fix:

1. Click the “Zoom” button in the toolbar to enable scaling mode so the image fits the window proportionally.
2. Or enter fullscreen (F11) and then use scaling.

Black screen after RDP connection

Troubleshooting:

1. Confirm Remote Desktop is enabled on the remote Windows (System Properties → Remote).
2. Confirm the user is in the Remote Desktop Users group.
3. Confirm the color depth setting is compatible with the server (try lowering to 16-bit).
4. Confirm the firewall allows port 3389.

14.4 Cloud Sync Issues

Cloud sync menu is grayed out

Cause: not signed in, or the plan does not support it.

Fix:

1. Sign in first (toolbar “Sign in”).
2. Confirm the plan is Pro or above (cloud sync is unavailable in Free / Trial).
3. If still grayed out after signing in, restart the app (plan feature gating is refreshed after login).

Session passwords lost after sync

Symptom: after syncing, some sessions have empty passwords and need to be re-entered.

Cause: the session’s encrypted password cannot be decrypted with this device’s masterKey (common after switching devices or when masterKeys differ). WxTerm automatically clears undecryptable passwords before uploading, to avoid wrong passwords spreading through sync.

Fix:

1. Check which sessions failed to decrypt in the sync result dialog.
2. Edit those sessions manually and re-enter the passwords.
3. To recover the original passwords, use the master key recovery flow to obtain the cloud masterKey.

masterKey mismatch

Symptom: the master key recovery dialog appears during a manual sync.

Fix:

• Recover: enter the recovery password to fetch the cloud masterKey and overwrite the local one; afterwards cloud session passwords can be decrypted.
• Cancel: keep the local masterKey and only sync data that does not involve passwords (session passwords remain undecryptable).

One-click login does not open the browser

Troubleshooting:

1. Confirm a default browser is configured on the system.
2. On Linux, confirm xdg-open is available.
3. Manually copy the login URL into a browser.

14.5 Performance Issues

Terminal feels sluggish

Troubleshooting:

1. Scrollback too large: reduce the scrollback lines in “Settings → Terminal → Misc Settings” (default 5000).
2. Background image opacity too high: lower the opacity or turn off the background image.
3. Remote desktop animation stutter: GNOME menu animations in VNC/RDP sessions may stutter; disable animation effects in the remote system.
4. Too many tabs: close unused tabs to reduce rendering load.

High memory usage

Troubleshooting:

1. Scrollback accumulates memory per tab; reduce the scrollback lines or close idle tabs.
2. Remote desktop caches frame data; close unused remote desktop windows.
3. Terminal logging writes to disk and caches continuously while enabled; turn it off if not needed.

14.6 AI Assistant Issues

“No model configured” after sending a message

Troubleshooting:

1. Open the “Model Config” button on the group right bar (visible when the AI panel is open) and confirm an API service has been added with at least one model enabled.
2. Click “Test Connection” to verify the API URL, key, and protocol type.
3. The API URL needs the version prefix (e.g. https://api.deepseek.com/v1); a missing /v1 is a common mistake.
4. For local Ollama, use http://127.0.0.1:11434/v1 and leave the key empty.

AI requests fail / keep retrying

On failure the AI retries automatically (up to 10 times, 3 seconds apart); the failure card shows the specific error:

1. Network problems: the API provider is unreachable; if a proxy is needed, configure it on the “Proxy” page of the model config and check “Use proxy” on the API.
2. Key/quota problems: check that the API key is valid and the account balance is sufficient.
3. Max output too large: some gateways reject max_tokens requests at the ceiling; lower the model’s “Max output”.
4. Click “Retry” on the failure card to resend manually.

AI runs commands but nothing happens

Troubleshooting:

1. Check whether an approval card is waiting for confirmation (in ask mode every command requires approval).
2. Device CLIs (firewalls/switches over Telnet/serial) have no POSIX shell; the AI first reads the screen to identify the environment and then switches to sending keystrokes — give it a moment.
3. If you typed in the terminal while the AI was running: the AI pauses to avoid fighting over the pipe; check the panel notice.

How to revoke an “Always Allow” command

Open the “Authorization Rules” button on the group right bar (visible when the AI panel is open) and delete the corresponding whitelist entry from the command list (or add it to the block list).

14.7 Other Issues

Configuration files lost

WxTerm stores its configuration in the configuration directory (see 01 Getting Started for its location). If that directory is deleted or has wrong permissions, configuration is lost:

1. Confirm the directory exists and is readable/writable by the current user.
2. If you have a cloud sync backup, sign in and restore sessions from the cloud.
3. Back up the directory regularly.

Shortcuts not working

Troubleshooting:

1. Check whether keymap.json in the configuration directory contains a conflicting mapping overriding the default shortcut (see 01 Getting Started for the directory location).
2. In the keymap editor, check whether a custom mapping occupies the same key combination.
3. Input methods may intercept some shortcuts; switch to the English input method and test again.

X11 forwarding: GUI programs don’t display

Troubleshooting:

1. Confirm X11Forwarding yes is enabled in the SSH server’s sshd_config.
2. Confirm xauth is installed on the remote.
3. Confirm the X11 forwarding rule is enabled and attached to the current session.
4. After connecting, run echo $DISPLAY on the remote; it should show something like localhost:10.0.

Slow application startup

Troubleshooting:

1. Startup cloud sync runs at launch; temporarily disable cloud sync on slow networks.
2. With many sessions the sidebar loads slightly slower; organize them into folders.
3. Check whether a corrupted configuration file is slowing down parsing.

14.8 Getting Help

• In-app: menu “Help → About WxTerm” for version info; “Help → Shortcuts” for the shortcut list.
• Official website: https://www.oupula.com/products/wxterm.html
• Check for updates: menu “Help → Check for Updates” to get the latest version.
• Log files: terminal logs under the logs subdirectory of the configuration directory help troubleshoot session issues (logging must be enabled in the session configuration; see 01 Getting Started for the directory location).