# AutoInterface Issue Resolution

**Date:** 2026-01-25
**Status:** RESOLVED

## Problem Summary

Q502 TCPClientInterface failed to load, preventing hub connection and fleet discovery. MacBook with identical RNS version and config worked correctly.

## Root Cause

**AutoInterface initialization errors blocked TCPClientInterface from loading on Q502.**

### Evidence

| System | Python | AutoInterface | TCPClientInterface | Result |
|--------|--------|---------------|-------------------|--------|
| Q502 (original config) | 3.11.11 | Enabled, erroring | ❌ Not loaded | No hub connection |
| Q502 (minimal config) | 3.11.11 | Disabled | ✅ Loaded | Hub connected |
| MacBook (original config) | 3.14.2 | Disabled | ✅ Loaded | Hub connected |

**Q502 AutoInterface error:**
```
[Error] AutoInterface[AutoInterface] No multicast echoes received on wlp3s0
```

This error occurred **before** RNS config parser processed the TCPClientInterface section, causing silent failure.

## Initial Hypotheses (Disproven)

1. **Python version mismatch** - ❌ Both 3.11.x and 3.14.2 work when AutoInterface is disabled
2. **RNS version** - ❌ Both systems run RNS 1.1.3
3. **Network connectivity** - ❌ TCP connectivity verified with `nc`
4. **Config file corruption** - ❌ Configs were identical
5. **RNS storage cache** - ⚠️ Contributing factor, but not root cause

## Solution

### New Standard: AutoInterface Disabled by Default

**Rationale:**
- **Linux:** AutoInterface errors on certain network adapters (wlp3s0) block subsequent interface initialization
- **macOS:** "No buffer space available" errors on VPN/tunnel interfaces (utun0-5)
- **General:** Silent failures prevent TCPClientInterface from loading

**Implementation:**

1. **Config Generation** (`src/styrene/services/reticulum.py:579`):
   - Reordered interfaces: TCPClientInterface BEFORE AutoInterface (higher priority)
   - Always include AutoInterface section with documentation
   - Default `enabled = false` with clear comments explaining why

2. **Default Config** (`src/styrene/models/config.py:203`):
   - Changed `auto: bool = True` → `auto: bool = False`
   - Added documentation explaining platform issues

3. **Production Configs** (Q502 + MacBook):
   - TCPClientInterface listed first
   - AutoInterface present but disabled
   - Comments explain when/how to enable AutoInterface safely

### Standard Config Format

```ini
[reticulum]
enable_transport = no
share_instance = false

[interfaces]

# Hub connection (highest priority)
[[Styrene Community Hub]]
type = TCPClientInterface
enabled = true
target_host = 192.168.0.102
target_port = 4242

# Local multicast discovery (disabled by default)
# IMPORTANT: AutoInterface disabled due to platform compatibility issues:
#   - Linux: Can error on certain adapters blocking subsequent interfaces
#   - macOS: VPN/tunnel interface errors
#   - General: Errors prevent TCPClientInterface from loading
#
# Enable only if you need local discovery AND have stable network adapters.
[[AutoInterface]]
type = AutoInterface
enabled = false
# To exclude problematic interfaces if enabling, add:
# ignored_interfaces = utun0,utun1,wlp3s0
```

## Verification Steps

1. **Clear RNS storage cache** (fresh identity generation)
2. **Apply standard config** (TCPClientInterface first, AutoInterface disabled)
3. **Test initialization:**
   - Q502: TCPClientInterface loads successfully
   - MacBook: TCPClientInterface loads successfully
   - Both connect to hub at 192.168.0.102:4242

## Lessons Learned

1. **Interface order matters** - RNS processes interfaces sequentially; errors can block subsequent interfaces
2. **Silent failures are dangerous** - RNS didn't log why TCPClientInterface wasn't loaded
3. **Platform differences** - What works on macOS may fail on Linux, and vice versa
4. **Default to reliable** - Hub-based fleet discovery is more robust than local multicast

## Related Documents

- `docs/Q502-TCPCLIENT-INVESTIGATION.md` - Detailed investigation log
- `docs/PYTHON-BASELINE.md` - Python version standardization
- `docs/DISCOVERY-FAILURE-ASSESSMENT.md` - Initial routing analysis

## Future Improvements

1. **Add RNS logging** to show why interfaces fail to load
2. **Pre-flight checks** for AutoInterface (test multicast before enabling)
3. **Config validator** to warn about problematic interface combinations
4. **Automated tests** for RNS config generation on both platforms
