Common Issues

Connection Issues

Client Can’t Connect to Server

Symptoms:

Connection refused
Connection timeout
Failed to connect

Verify Server is Running

# Check if server is listening
netstat -ano | findstr :2022

# Should show:
# TCP    0.0.0.0:2022    0.0.0.0:0    LISTENING    <PID>

If not listening:

# Start server
./undying-terminal-server.exe

Check Firewall

# Windows Firewall
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*Undying*"}

# If no rule exists:
./undying-terminal-server.exe --add-firewall

Third-party firewalls: Add exception for undying-terminal-server.exe on port 2022

Test Network Connectivity

# Test if port is reachable
Test-NetConnection -ComputerName <HOST> -Port 2022

# Should show:
# TcpTestSucceeded : True

If fails:

Check router port forwarding
Check network path (VPN, proxy)
Try localhost first (127.0.0.1)

Verify Credentials

Client ID and passkey must match exactly:

# Terminal output when started:
[TERMINAL] Client ID: abc123def456
[TERMINAL] Passkey: 1234567890abcdef

# Client must use exact values:
--connect <HOST> 2022 abc123def456 --key 1234567890abcdef

Common mistakes:

Wrong client ID (typo)
Wrong passkey (case-sensitive hex)
Using old credentials (terminal restarted)

Check Encryption Mismatch

Server and client must agree on encryption:

# Server config (ut.cfg)
shared_key_hex=abc123...

# Client MUST use same key
# If server has key, client needs it
# If server has NO key, client shouldn't try to encrypt

Still stuck? Enable debug logging:

$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal.exe --connect ...

Look for specific error messages in output.

Authentication Failed - Invalid Passkey

Error: ConnectResponse(status=INVALID_KEY) Cause: Passkey mismatch between client and server Solutions:

Solution 1: Verify Passkey

Get passkey from terminal output:

# When terminal starts:
echo "test" | ./undying-terminal-terminal.exe

# Output:
[TERMINAL] Client ID: abc123def456
[TERMINAL] Passkey: 1234567890abcdef  <-- Use this EXACT value

Use exact hex string in client:

--key 1234567890abcdef

Solution 2: Restart Terminal

If terminal was restarted, passkey changed:

# 1. Stop old terminal (if running)
taskkill /IM undying-terminal-terminal.exe /F

# 2. Start fresh
echo "test" | ./undying-terminal-terminal.exe

# 3. Note NEW client ID and passkey
# 4. Update client connection command

Solution 3: Check Encryption Key

If server uses encryption, ensure it’s configured:

# Server: ut.cfg
shared_key_hex=<key>

Mismatch will cause authentication to fail silently.

Session Won’t Reconnect After Disconnect

Symptoms:

Client exits instead of reconnecting
Session terminated message
No automatic retry

Causes & Solutions:

Cause	Solution
Terminal process died	Restart terminal: `echo "test" \| ./undying-terminal-terminal.exe`
Server crashed	Restart server: `./undying-terminal-server.exe`
Passkey changed	Terminal restarted → passkey changed → use new passkey
Network path broken	Check VPN, proxy, routing
Client in one-shot mode	Don’t use `-c` without `--noexit` for interactive sessions

Debug:

# Check if terminal is alive
tasklist | findstr undying-terminal-terminal

# Check if server is alive
tasklist | findstr undying-terminal-server

# Check network
Test-NetConnection <HOST> -Port 2022

Performance Issues

High Latency / Slow Response

Symptoms:

Keystrokes appear after delay
Slow command output
Laggy terminal

Measure Network Latency

ping <server-host>

# Check:
# - Average latency (should be <100ms for good experience)
# - Packet loss (should be 0%)

Expected:

LAN: 1-5ms
Internet: 20-100ms
International: 100-300ms

If high:

Check network path (tracert)
Check bandwidth (speedtest)
Consider closer server

Check Recovery Buffer

After reconnect, large buffer replay causes delay:

# Enable debug to see catchup size
$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal.exe --connect ...

# Look for:
# [DEBUG] Sending catchup: X bytes

If large (>10MB):

Wait for catchup to complete
To reduce keepalive frequency: requires a recompile

Check Server Load

# On server machine:
tasklist | findstr undying-terminal-server

# Check:
# - Memory usage (should be <500MB for <100 sessions)
# - CPU usage (should be <10% idle)

If high:

Reduce concurrent sessions
Add more RAM/CPU
Check for runaway terminal processes

Disable Encryption (Test)

Temporarily disable encryption to isolate issue:

# ut.cfg
# shared_key_hex=...  <-- Comment out

Restart server and test. If faster, encryption overhead is the issue (should be <1ms though).

Memory Usage Growing

Symptoms:

Server memory increases over time
Eventually crashes or slows down

Causes:

Recovery Buffer Growth (expected)
- Each session: up to 128MB (64MB × 2 directions)
- 10 sessions: up to 1.28GB
- Normal behavior
Memory Leak (bug)
- Stale sessions not cleaned up
- Known issue: Server doesn’t clean up on pipe disconnect

Solutions:

# Check memory usage
Get-Process undying-terminal-server | Select-Object PM,VM,WS

# PM (Private Memory): Actual usage
# Normal: 50MB + (5MB × active_sessions)

# Schedule periodic restart (daily/weekly)
$action = New-ScheduledTaskAction `
  -Execute "PowerShell.exe" `
  -Argument "-Command Restart-Service UndyingTerminalServer"

$trigger = New-ScheduledTaskTrigger -Daily -At 3am

Register-ScheduledTask `
  -TaskName "Restart Undying Terminal Server" `
  -Action $action `
  -Trigger $trigger

# Manually kill stale terminal processes
tasklist | findstr undying-terminal-terminal
# Kill PIDs with no active connection

Terminal Issues

Shell Exits Unexpectedly

Symptoms:

Terminal process terminates
Session ends
Must restart terminal

Common Causes:

Cause	Trigger	Prevention
User exits shell	`exit`, `Ctrl+D`	Never exit shell, disconnect client instead
Shell crash	Syntax error, segfault	Fix script errors
ConPTY error	Windows bug	Update Windows
Terminal timeout	Idle too long	Keep client connected or use screen/tmux

Solution: Restart terminal

echo "test" | ./undying-terminal-terminal.exe
# Note new client ID and passkey

Garbled Output / Encoding Issues

Symptoms:

Special characters appear as ? or boxes
Colors broken
Line wrapping wrong

Solutions:

UTF-8 Encoding
Terminal Resize
Clear Screen

# PowerShell: Set output encoding
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::UTF8

# CMD: Use UTF-8 code page
chcp 65001

# Resize client terminal window
# ConPTY should auto-adjust

# If not working, send resize signal manually:
# (Not yet implemented - resize on window change only)

# CMD
cls

# PowerShell
clear

# Bash (if using)
reset

Colors Not Working

Cause: ConPTY virtual terminal sequences not enabled Solution:

# PowerShell: Enable VT100
[Console]::OutputEncoding = [Text.UTF8Encoding]::UTF8
$PSStyle.OutputRendering = 'Ansi'

# CMD: Already supported in Windows 10+

Configuration Issues

Config File Not Loading

Symptoms:

Server uses default values
Changes in ut.cfg ignored

Checklist:

Correct location:

# Should be:
$env:PROGRAMDATA\UndyingTerminal\ut.cfg
# Usually:
C:\ProgramData\UndyingTerminal\ut.cfg

File permissions:

# Check if server can read file
Get-Acl "$env:PROGRAMDATA\UndyingTerminal\ut.cfg"

File format:

# Correct:
port=2022

# Incorrect:
port = 2022  # No spaces around =
"port"=2022  # No quotes

Server restart:

# Config only read on startup
Restart-Service UndyingTerminalServer
# OR
# Kill and restart manually

Port Already in Use

Error: bind: address already in use

Find Process Using Port

netstat -ano | findstr :2022
# TCP    0.0.0.0:2022    ...    LISTENING    <PID>

tasklist | findstr <PID>

Choose Solution

Option A: Kill the process

Stop-Process -Id <PID> -Force

Option B: Change port

# ut.cfg
port=2023

Option C: Command-line override

./undying-terminal-server.exe --port 2023

Named Pipe Errors

Error: Failed to connect to named pipe Causes:

Server not running:

netstat -ano | findstr :2022
# Should show LISTENING

Wrong pipe name:

# Server uses:
$env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-custom"

# Terminal MUST use same:
$env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-custom"
echo "test" | ./undying-terminal-terminal.exe

Permission denied:
- Run as same user as server
- Or grant permissions (advanced)

Tunnel / Port Forwarding Issues

Tunnel Not Working

Symptoms:

Connection to forwarded port fails
Connection refused on tunnel

Forward Tunnel: Connection Refused

# Client: -t 8080:remote-service:9090
# Trying: localhost:8080
# Error: Connection refused

Checklist:

Service running on remote? netstat -ano | findstr :9090 (on server)
Firewall blocking? Check server firewall rules
Correct destination? Try telnet remote-service 9090 from server
Tunnel established? Check client output for tunnel messages

Reverse Tunnel: Not Accessible

# Client: -r 3000:localhost:8000
# Server should listen on 3000
# But connection fails

Checklist:

Server listening? netstat -ano | findstr :3000 (on server)
Local service running? netstat -ano | findstr :8000 (on client)
Client connected? Session must be active
Firewall on server? Check inbound rules for port 3000

Port Already in Use

Error: bind: address already in use

Forward tunnel: Local port already used

# Find what's using the port
netstat -ano | findstr :8080

# Choose different local port
-t 8081:remote:9090  # Changed 8080 → 8081

Reverse tunnel: Server port already used

# On server, find conflicting process
netstat -ano | findstr :3000

# Choose different remote port
-r 3001:localhost:8000  # Changed 3000 → 3001

Tunnel Breaks After Reconnect

Expected Behavior: Active TCP connections through tunnels do not survive client reconnects. Why: Both ends of TCP connection must be preserved. When client disconnects:

Client-side connections drop
Server-side connections drop
Applications must reconnect

Workaround: Design applications with reconnect logic What DOES survive: Tunnel infrastructure (listeners restart automatically)

Windows-Specific Issues

ConPTY Errors

Error: CreatePseudoConsole failed Cause: Windows version < Build 17763 Solution: Update Windows

# Check version
winver

# Required: Windows 10 Build 17763+ (October 2018)
# Update via Windows Update

Service Won’t Start

Error: The service did not respond to the start or control request in a timely fashion Solutions:

Check service config:
sc.exe query UndyingTerminalServer

Check binary path:

sc.exe qc UndyingTerminalServer
# binPath should be correct

Check permissions:
- Service runs as SYSTEM by default
- Config file must be readable by SYSTEM

Check logs:

# Event Viewer → Windows Logs → Application
# Look for UndyingTerminalServer errors

DLL Missing Errors

Error: The code execution cannot proceed because libsodium.dll was not found Cause: Required DLLs not in PATH or binary directory Solution:

# Copy DLLs to binary directory
Copy-Item "C:\path\to\deps\*.dll" "C:\Program Files\UndyingTerminal\"

# Or add to PATH
$path = [Environment]::GetEnvironmentVariable('Path', 'Machine')
$newPath = "$path;C:\path\to\deps"
[Environment]::SetEnvironmentVariable('Path', $newPath, 'Machine')

Required DLLs:

libsodium.dll
libcrypto-*.dll (OpenSSL)
libssl-*.dll (OpenSSL)

Getting More Help

Enable Verbose Logging

# Server: Edit ut.cfg
verbose=true

# Client: Environment variable
$env:UT_DEBUG_HANDSHAKE = 1

# Run and capture output
./undying-terminal.exe --connect ... > client.log 2>&1

Collect Diagnostic Information

Before reporting issues:

# 1. Version info
./undying-terminal.exe --version

# 2. Windows version
winver

# 3. Network status
netstat -ano | findstr :2022
Test-NetConnection <HOST> -Port 2022

# 4. Process list
tasklist | findstr undying

# 5. Logs (if verbose=true)
Get-Content server.log -Tail 50

Report a Bug

Include in your report:

Steps to reproduce
Expected behavior
Actual behavior
Diagnostic information (above)
Error messages (full output)

GitHub Issues: https://github.com/Microck/UndyingTerminal/issues

Getting Started

Core Concepts

Configuration

Troubleshooting

Development

Connection Issues

Client Can’t Connect to Server

Authentication Failed - Invalid Passkey

Session Won’t Reconnect After Disconnect

Performance Issues

High Latency / Slow Response

Memory Usage Growing

Terminal Issues

Shell Exits Unexpectedly

Garbled Output / Encoding Issues

Colors Not Working

Configuration Issues

Config File Not Loading

Port Already in Use

Named Pipe Errors

Tunnel / Port Forwarding Issues

Tunnel Not Working

Tunnel Breaks After Reconnect

Windows-Specific Issues

ConPTY Errors

Service Won’t Start

DLL Missing Errors

Getting More Help

Enable Verbose Logging

Collect Diagnostic Information

Report a Bug

​Connection Issues

​Client Can’t Connect to Server

​Authentication Failed - Invalid Passkey

​Session Won’t Reconnect After Disconnect

​Performance Issues

​High Latency / Slow Response

​Memory Usage Growing

​Terminal Issues

​Shell Exits Unexpectedly

​Garbled Output / Encoding Issues

​Colors Not Working

​Configuration Issues

​Config File Not Loading

​Port Already in Use

​Named Pipe Errors

​Tunnel / Port Forwarding Issues

​Tunnel Not Working

​Tunnel Breaks After Reconnect

​Windows-Specific Issues

​ConPTY Errors

​Service Won’t Start

​DLL Missing Errors

​Getting More Help

​Enable Verbose Logging

​Collect Diagnostic Information

​Report a Bug

Connection Issues

Client Can’t Connect to Server

Authentication Failed - Invalid Passkey

Session Won’t Reconnect After Disconnect

Performance Issues

High Latency / Slow Response

Memory Usage Growing

Terminal Issues

Shell Exits Unexpectedly

Garbled Output / Encoding Issues

Colors Not Working

Configuration Issues

Config File Not Loading

Port Already in Use

Named Pipe Errors

Tunnel / Port Forwarding Issues

Tunnel Not Working

Tunnel Breaks After Reconnect

Windows-Specific Issues

ConPTY Errors

Service Won’t Start

DLL Missing Errors

Getting More Help

Enable Verbose Logging

Collect Diagnostic Information

Report a Bug