Client updates rename things. Not often, not loudly, and usually without a changelog entry that
says "this will break your config." I've now been bitten by the same six fields enough times to
check them first whenever a working setup stops working after an update.
None of these are exotic. That's the point — they're common enough that most configs contain
them.
1. mixed-port vs port + socks-port
Older configs declare HTTP and SOCKS on separate ports. Newer cores accept mixed-port and some
front-ends only read that. If your config has port: 7890 but no mixed-port, the UI may show
"no proxy configured" while the core is actually listening fine.
Symptom: the client works, but nothing routes through it.
Fix: add mixed-port: 7890 and keep the old keys for compatibility.
2. dns.enhanced-mode
redir-host and fake-ip are not interchangeable, and the default flipped at some point in most
client lineages. A config written for redir-host used under a fake-ip default resolves
differently, and the failure shows up as "some sites don't load" rather than a clean error.
This is the single field I've seen cause the most confusing post-update behaviour, because the
config is valid either way — it just does something different.
3. allow-lan
Defaults to false, and some updates reset it. If you rely on a phone or a TV routing through the
desktop client, the update silently cuts them off while the desktop keeps working.
Symptom: "it works on my PC but not on my phone" after an update that "changed nothing".
4. external-controller binding
127.0.0.1:9090 vs 0.0.0.0:9090. Updates sometimes tighten this to loopback for security,
which breaks any dashboard you access from another machine — including a phone-based dashboard
app. The core is running; the API just isn't reachable.
5. geodata-mode / geosite paths
Cores differ on whether they read .dat files or .mmdb/.mrs rule sets. After an upgrade that
switches the geo backend, a config pointing at geosite.dat may fail to load with an error that
mentions neither geo nor the path.
Symptom: core won't start, error references a file you never touched.
6. tun.stack
gvisor vs system vs mixed. Default changed across versions, and the wrong choice shows up as
either "connected but slow" or "some apps can't connect at all" — never as a clear failure. On
Linux, system needs the right kernel modules; gvisor avoids that but adds latency.
The general pattern
Every one of these fails the same way: the config remains syntactically valid, so the client
loads it without complaint, and the failure appears somewhere else entirely.
That's what makes updates feel random. The parser has nothing to complain about.
A habit worth adopting
Before updating, snapshot the whole profile directory, not just config.yaml:
cp -a ~/.config/<client> ~/.config/<client>.bak-$(date +%F)
Then after the update, diff the effective config (what the client reports it's using) against
the snapshot. Most clients expose this in the dashboard or via the external controller API:
curl -s http://127.0.0.1:9090/configs | jq .
Nine times out of ten the diff shows one of the six fields above changed, and you're done in two
minutes instead of an afternoon.
I keep a field-by-field reference for these across client versions at
the error-string index
— corrections welcome, especially for clients I don't run.
Top comments (0)