Troubleshooting

If you encounter issues while using PhanTerm, please refer to the following troubleshooting guide.

1. Terminal Rendering or Text Overlap Issues

Symptom: After entering the terminal, certain complex command-line applications (like apps utilizing automatic line wrapping for long commands, or multi-colored Git logs) display misaligned text, visual ghosting, or incorrect cursor positioning.

Solution: This is usually caused by a desynchronization between the terminal dimensions detected by the OS and the actual window size. Please try manually resizing your window by dragging the borders. Once PhanTerm’s listener detects the Resize event, it forces a correct dimension reset to the remote PTY, which resolves over 90% of visual glitch issues.

2. Cannot Connect to Server (Connection Timed Out)

Symptom: The Connecting... spinning animation plays continuously, eventually throwing a timeout or network unreachable error.

Solution:

1. First, double-check that the IP and port (especially custom non-22 ports) you entered are correct.
2. Confirm that the remote machine’s firewall or your cloud provider’s security group has allowed your local public IP.
3. If the target server is located in an internal network, you might need to configure a ProxyJump (Bastion Host) in the connection settings to pierce through.

3. SSH Key Authentication Refused (Permission Denied)

Symptom: You have configured key-based authentication, but you are still prompted for a password or the connection fails outright.

Solution:

1. Verify Path: Check that the IdentityFile path you provided exists and is valid.
2. Format Check: Ensure you provided the private key file (like id_rsa or id_ed25519), NOT the public key file with a .pub extension.
3. System Agent: If you opted to rely on the system’s ssh-agent or Pageant for management, verify that these background services are running and that your keys have been properly loaded into the system via ssh-add.

4. Red Screen Warning for Host Key Mismatch

Symptom: A severe red warning dialog pops up during connection, indicating an invalid host key signature.

Solution: Do not hastily bypass this! Please contact your server administrator first. You should only consider this normal under two conditions:

1. The operating system was recently reinstalled.
2. The administrator informed you that the SSH security certificates were just rotated.

Once you confirm it is secure, you can navigate to your local configuration directory (refer to the Settings Reference), manually delete the conflicting record line from known_hosts.yaml, and try connecting again.