> ## Documentation Index
> Fetch the complete documentation index at: https://undyingterminal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Solutions to frequently encountered problems

## Connection Issues

### Client Can't Connect to Server

**Symptoms**:

* `Connection refused`
* `Connection timeout`
* `Failed to connect`

<Steps>
  <Step title="Verify Server is Running">
    ```powershell theme={null}
    # 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:

    ```powershell theme={null}
    # Start server
    ./undying-terminal-server.exe
    ```
  </Step>

  <Step title="Check Firewall">
    ```powershell theme={null}
    # 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
  </Step>

  <Step title="Test Network Connectivity">
    ```powershell theme={null}
    # 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`)
  </Step>

  <Step title="Verify Credentials">
    Client ID and passkey must match exactly:

    ```powershell theme={null}
    # 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)
  </Step>

  <Step title="Check Encryption Mismatch">
    Server and client must agree on encryption:

    ```powershell theme={null}
    # 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
    ```
  </Step>
</Steps>

<Warning title="Debug Mode">
  Still stuck? Enable debug logging:

  ```powershell theme={null}
  $env:UT_DEBUG_HANDSHAKE = 1
  ./undying-terminal.exe --connect ...
  ```

  Look for specific error messages in output.
</Warning>

### Authentication Failed - Invalid Passkey

**Error**: `ConnectResponse(status=INVALID_KEY)`

**Cause**: Passkey mismatch between client and server

**Solutions**:

<AccordionGroup>
  <Accordion title="Solution 1: Verify Passkey">
    Get passkey from terminal output:

    ```powershell theme={null}
    # 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:

    ```powershell theme={null}
    --key 1234567890abcdef
    ```
  </Accordion>

  <Accordion title="Solution 2: Restart Terminal">
    If terminal was restarted, passkey changed:

    ```powershell theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Solution 3: Check Encryption Key">
    If server uses encryption, ensure it's configured:

    ```ini theme={null}
    # Server: ut.cfg
    shared_key_hex=<key>
    ```

    Mismatch will cause authentication to fail silently.
  </Accordion>
</AccordionGroup>

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

```powershell theme={null}
# 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

<Steps>
  <Step title="Measure Network Latency">
    ```powershell theme={null}
    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
  </Step>

  <Step title="Check Recovery Buffer">
    After reconnect, large buffer replay causes delay:

    ```powershell theme={null}
    # 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
  </Step>

  <Step title="Check Server Load">
    ```powershell theme={null}
    # 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
  </Step>

  <Step title="Disable Encryption (Test)">
    Temporarily disable encryption to isolate issue:

    ```ini theme={null}
    # ut.cfg
    # shared_key_hex=...  <-- Comment out
    ```

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

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

<CodeGroup>
  ```powershell Monitor Memory theme={null}
  # Check memory usage
  Get-Process undying-terminal-server | Select-Object PM,VM,WS

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

  ```powershell Restart Server (Workaround) theme={null}
  # 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
  ```

  ```powershell Clean Stale Sessions theme={null}
  # Manually kill stale terminal processes
  tasklist | findstr undying-terminal-terminal
  # Kill PIDs with no active connection
  ```
</CodeGroup>

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

```powershell theme={null}
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**:

<Tabs>
  <Tab title="UTF-8 Encoding">
    ```powershell theme={null}
    # PowerShell: Set output encoding
    $OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::UTF8

    # CMD: Use UTF-8 code page
    chcp 65001
    ```
  </Tab>

  <Tab title="Terminal Resize">
    ```powershell theme={null}
    # Resize client terminal window
    # ConPTY should auto-adjust

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

  <Tab title="Clear Screen">
    ```powershell theme={null}
    # CMD
    cls

    # PowerShell
    clear

    # Bash (if using)
    reset
    ```
  </Tab>
</Tabs>

### Colors Not Working

**Cause**: ConPTY virtual terminal sequences not enabled

**Solution**:

```powershell theme={null}
# 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**:
   ```powershell theme={null}
   # Should be:
   $env:PROGRAMDATA\UndyingTerminal\ut.cfg
   # Usually:
   C:\ProgramData\UndyingTerminal\ut.cfg
   ```

2. **File permissions**:
   ```powershell theme={null}
   # Check if server can read file
   Get-Acl "$env:PROGRAMDATA\UndyingTerminal\ut.cfg"
   ```

3. **File format**:
   ```ini theme={null}
   # Correct:
   port=2022

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

4. **Server restart**:
   ```powershell theme={null}
   # Config only read on startup
   Restart-Service UndyingTerminalServer
   # OR
   # Kill and restart manually
   ```

### Port Already in Use

**Error**: `bind: address already in use`

<Steps>
  <Step title="Find Process Using Port">
    ```powershell theme={null}
    netstat -ano | findstr :2022
    # TCP    0.0.0.0:2022    ...    LISTENING    <PID>

    tasklist | findstr <PID>
    ```
  </Step>

  <Step title="Choose Solution">
    **Option A**: Kill the process

    ```powershell theme={null}
    Stop-Process -Id <PID> -Force
    ```

    **Option B**: Change port

    ```ini theme={null}
    # ut.cfg
    port=2023
    ```

    **Option C**: Command-line override

    ```powershell theme={null}
    ./undying-terminal-server.exe --port 2023
    ```
  </Step>
</Steps>

### Named Pipe Errors

**Error**: `Failed to connect to named pipe`

**Causes**:

1. **Server not running**:
   ```powershell theme={null}
   netstat -ano | findstr :2022
   # Should show LISTENING
   ```

2. **Wrong pipe name**:
   ```powershell theme={null}
   # 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

<AccordionGroup>
  <Accordion title="Forward Tunnel: Connection Refused">
    ```powershell theme={null}
    # 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
  </Accordion>

  <Accordion title="Reverse Tunnel: Not Accessible">
    ```powershell theme={null}
    # 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
  </Accordion>

  <Accordion title="Port Already in Use">
    ```bash theme={null}
    Error: bind: address already in use
    ```

    **Forward tunnel**: Local port already used

    ```powershell theme={null}
    # 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

    ```powershell theme={null}
    # On server, find conflicting process
    netstat -ano | findstr :3000

    # Choose different remote port
    -r 3001:localhost:8000  # Changed 3000 → 3001
    ```
  </Accordion>
</AccordionGroup>

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

```powershell theme={null}
# 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**:
   ```powershell theme={null}
   sc.exe query UndyingTerminalServer
   ```

2. **Check binary path**:
   ```powershell theme={null}
   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**:
   ```powershell theme={null}
   # 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**:

```powershell theme={null}
# 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

```powershell theme={null}
# 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:

```powershell theme={null}
# 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](https://github.com/Microck/UndyingTerminal/issues)