Troubleshooting¶

/dev/net/tun is missing¶

Check whether the provider exposes TUN:

ls -l /dev/net/tun

On a VPS/container, this may require a provider-side setting. tcpcc cannot emulate a missing TUN device inside the current architecture.

Forwarding check fails¶

Check the selected public family:

sysctl net.ipv4.ip_forward
sysctl net.ipv6.conf.all.forwarding

tcpcc reports this prerequisite but does not silently change the global sysctl.

BBR is absent from the outer host¶

That alone is not a problem.

Do not use the outer host's net.ipv4.tcp_available_congestion_control as proof that hosted BBR is unavailable. The public listener lives in hosted Linux, where tcpcc sets and reads back TCP_CONGESTION.

Backend is rejected¶

The current backend contract is IPv4 loopback only:

127.0.0.1:PORT

A non-loopback backend address is rejected intentionally.

IPv6 endpoint fails to parse¶

Use brackets around the literal:

[2001:db8::10]:443

not:

2001:db8::10:443

Mixed IPv4 and IPv6 forwards are rejected¶

All public listeners in one tcpcc process currently share one TUN/L3 endpoint and therefore one public address family. Use separate tcpcc processes if both families are required.

Duplicate public ports are rejected¶

Public ports must be unique within one process even when the public addresses differ. DNAT preserves the port when mapping into the shared hosted endpoint.

Config file and CLI options conflict¶

When --config FILE is selected, do not also pass direct service options such as --forward, --cc, or --memory-mib.

The supported validation form is:

sudo tcpcc --check --config /etc/tcpcc/tcpcc.toml

Resident memory is lower than --memory-mib¶

This is expected. The guest-capacity arena is demand-backed; configured guest RAM and host resident memory are different quantities.

Resident memory does not fall immediately after closing flows¶

Also expected. Bridge teardown does not prove that every guest TCP control block has completed its close/orphan lifetime. M10 treats immediate reclaim behavior as telemetry and uses repeated post-load resident-floor stability as the hard long-running memory criterion.

More diagnostics¶

The canonical architecture and detailed milestone documents are in the main repository.