Common Issues

Solutions to frequently encountered problems

Connection Issues

Client Can’t Connect to Server

Symptoms:

• Connection refused
• Connection timeout
• Failed to connect

1. 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
   
2. 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

3. 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)
4. 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)
5. 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

1. 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
2. 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
3. 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
4. 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:

1. Recovery Buffer Growth (expected)

   • Each session: up to 128MB (64MB × 2 directions)
   • 10 sessions: up to 1.28GB
   • Normal behavior

2. Memory Leak (bug)

   • Stale sessions not cleaned up
   • Known issue: Server doesn’t clean up on pipe disconnect

Solutions:

Monitor Memory

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

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

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

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

# CMD: Use UTF-8 code page
chcp 65001

Terminal Resize

# Resize client terminal window
# ConPTY should auto-adjust

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

Clear Screen

# 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:

1. Correct location:

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

2. File permissions:

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

3. File format:

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

4. 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

1. Find Process Using Port

   netstat -ano | findstr :2022
   # TCP    0.0.0.0:2022    ...    LISTENING    <PID>
   
   tasklist | findstr <PID>
   
2. 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:

1. Server not running:

   netstat -ano | findstr :2022
   # Should show LISTENING
   

2. 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
   

3. 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:

1. Service running on remote? netstat -ano | findstr :9090 (on server)
2. Firewall blocking? Check server firewall rules
3. Correct destination? Try telnet remote-service 9090 from server
4. 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:

1. Server listening? netstat -ano | findstr :3000 (on server)
2. Local service running? netstat -ano | findstr :8000 (on client)
3. Client connected? Session must be active
4. 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:

1. Check service config:

   sc.exe query UndyingTerminalServer
   

2. Check binary path:

   sc.exe qc UndyingTerminalServer
   # binPath should be correct
   

3. Check permissions:

   • Service runs as SYSTEM by default
   • Config file must be readable by SYSTEM

4. 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:

1. Steps to reproduce
2. Expected behavior
3. Actual behavior
4. Diagnostic information (above)
5. Error messages (full output)

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