Troubleshooting

Diagnosis and solutions for common Two-Face issues.

Quick Diagnosis

Issue Categories

First Steps

Before diving into specific issues, try these general steps:

1. Check Logs

# View recent logs
tail -100 ~/.two-face/two-face.log

# Watch logs in real-time
tail -f ~/.two-face/two-face.log

2. Verify Configuration

# Validate config syntax
two-face --check-config

# Start with defaults (bypass config issues)
two-face --default-config

3. Update Two-Face

# Check current version
two-face --version

# Download latest release from GitHub

4. Check Dependencies

# Linux - verify libraries
ldd $(which two-face)

# macOS - check dylibs
otool -L $(which two-face)

Log Levels

Increase logging for diagnosis:

# config.toml
[logging]
level = "debug"  # trace, debug, info, warn, error
file = "~/.two-face/two-face.log"

Log level details:

• error - Only critical failures
• warn - Warnings and errors
• info - Normal operation (default)
• debug - Detailed operation
• trace - Very verbose (large files)

Common Patterns

Configuration Issues

Symptom: Two-Face exits immediately or shows “config error”

Diagnosis:

# Check for TOML syntax errors
two-face --check-config 2>&1 | head -20

Common causes:

• Missing quotes around strings with special characters
• Unclosed brackets or braces
• Invalid key names
• Wrong data types

Connection Issues

Symptom: “Connection refused” or timeout

Diagnosis:

# Test Lich connection
nc -zv 127.0.0.1 8000

# Test direct connection
nc -zv eaccess.play.net 7910

Display Issues

Symptom: Missing colors, garbled text, wrong symbols

Diagnosis:

# Check terminal capabilities
echo $TERM
tput colors

# Test Unicode support
echo "╔═══╗ ← Should show box drawing"

Getting Help

Information to Collect

When reporting issues, include:

1. Version: two-face --version
2. Platform: Windows/macOS/Linux version
3. Terminal: What terminal emulator
4. Config: Relevant config sections (redact credentials!)
5. Logs: Recent log entries
6. Steps: How to reproduce

Report Template

**Version**: 0.1.0
**Platform**: Ubuntu 22.04
**Terminal**: Alacritty 0.12

**Description**:
What happened

**Expected**:
What should happen

**Steps to Reproduce**:
1. Start Two-Face with...
2. Do this...
3. See error

**Relevant Config**:
```toml
[connection]
mode = "lich"

Log Output:

[ERROR] relevant log lines

### Support Channels

1. **GitHub Issues**: Bug reports and feature requests
2. **GitHub Discussions**: Questions and help
3. **Documentation**: Check relevant sections first

## Troubleshooting Guides

### By Issue Type

- [Common Errors](./common-errors.md) - Error messages and solutions
- [Platform Issues](./platform-issues.md) - OS-specific problems
- [Performance Issues](./performance-issues.md) - Speed and responsiveness
- [Display Issues](./display-issues.md) - Visual problems
- [Connection Issues](./connection-issues.md) - Network problems

### By Symptom

| I see... | Check |
|----------|-------|
| "Config error" | [Common Errors](./common-errors.md#configuration-errors) |
| "Connection refused" | [Connection Issues](./connection-issues.md#connection-refused) |
| "Certificate error" | [Connection Issues](./connection-issues.md#certificate-issues) |
| Garbled text | [Display Issues](./display-issues.md#character-encoding) |
| Wrong colors | [Display Issues](./display-issues.md#color-problems) |
| Slow scrolling | [Performance Issues](./performance-issues.md#scroll-performance) |
| High CPU | [Performance Issues](./performance-issues.md#cpu-usage) |
| Crash on start | [Platform Issues](./platform-issues.md) |

## Quick Fixes

### Reset to Defaults

```bash
# Backup current config
mv ~/.two-face ~/.two-face.backup

# Start fresh - Two-Face creates defaults
two-face

Force Reconnect

In Two-Face:

.reconnect

Or restart:

# Kill existing process
pkill two-face

# Start fresh
two-face

Clear Cache

# Remove cached data
rm -rf ~/.two-face/cache/

# Remove certificate (re-downloads)
rm ~/.two-face/simu.pem

Diagnostic Mode

Start with extra diagnostics:

# Maximum verbosity
TF_LOG=trace two-face --debug

# Log to specific file
TF_LOG_FILE=/tmp/tf-debug.log two-face

See Also

• Installation - Setup instructions
• Configuration - Config reference
• Network - Connection setup