<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Jiedian Handbook]]></title><description><![CDATA[Jiedian Handbook]]></description><link>https://jiedianshouce.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sun, 22 Nov 2026 17:13:41 GMT</lastBuildDate><atom:link href="https://jiedianshouce.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Six config fields that break after a proxy client update]]></title><description><![CDATA[After a proxy client update, six config fields silently change format. Which ones break, and how to diff your old profile against the new one.]]></description><link>https://jiedianshouce.hashnode.dev/six-config-fields-that-break-after-a-proxy-client-update</link><guid isPermaLink="true">https://jiedianshouce.hashnode.dev/six-config-fields-that-break-after-a-proxy-client-update</guid><category><![CDATA[tooling]]></category><category><![CDATA[debugging]]></category><category><![CDATA[Open Source]]></category><dc:creator><![CDATA[dong liu]]></dc:creator><pubDate>Tue, 17 Nov 2026 07:21:05 GMT</pubDate><content:encoded><![CDATA[<p>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.</p>
<p>None of these are exotic. That's the point — they're common enough that most configs contain
them.</p>
<h3>1. <code>mixed-port</code> vs <code>port</code> + <code>socks-port</code></h3>
<p>Older configs declare HTTP and SOCKS on separate ports. Newer cores accept <code>mixed-port</code> and some
front-ends only read that. If your config has <code>port: 7890</code> but no <code>mixed-port</code>, the UI may show
"no proxy configured" while the core is actually listening fine.</p>
<p>Symptom: the client works, but nothing routes through it.
Fix: add <code>mixed-port: 7890</code> and keep the old keys for compatibility.</p>
<h3>2. <code>dns.enhanced-mode</code></h3>
<p><code>redir-host</code> and <code>fake-ip</code> are not interchangeable, and the default flipped at some point in most
client lineages. A config written for <code>redir-host</code> used under a <code>fake-ip</code> default resolves
differently, and the failure shows up as "some sites don't load" rather than a clean error.</p>
<p>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.</p>
<h3>3. <code>allow-lan</code></h3>
<p>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.</p>
<p>Symptom: "it works on my PC but not on my phone" after an update that "changed nothing".</p>
<h3>4. <code>external-controller</code> binding</h3>
<p><code>127.0.0.1:9090</code> vs <code>0.0.0.0:9090</code>. 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.</p>
<h3>5. <code>geodata-mode</code> / <code>geosite</code> paths</h3>
<p>Cores differ on whether they read <code>.dat</code> files or <code>.mmdb</code>/<code>.mrs</code> rule sets. After an upgrade that
switches the geo backend, a config pointing at <code>geosite.dat</code> may fail to load with an error that
mentions neither geo nor the path.</p>
<p>Symptom: core won't start, error references a file you never touched.</p>
<h3>6. <code>tun.stack</code></h3>
<p><code>gvisor</code> vs <code>system</code> vs <code>mixed</code>. 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, <code>system</code> needs the right kernel modules; <code>gvisor</code> avoids that but adds latency.</p>
<h3>The general pattern</h3>
<p>Every one of these fails the same way: <strong>the config remains syntactically valid, so the client
loads it without complaint, and the failure appears somewhere else entirely.</strong></p>
<p>That's what makes updates feel random. The parser has nothing to complain about.</p>
<h3>A habit worth adopting</h3>
<p>Before updating, snapshot the whole profile directory, not just <code>config.yaml</code>:</p>
<pre><code class="language-bash">cp -a ~/.config/&lt;client&gt; ~/.config/&lt;client&gt;.bak-$(date +%F)
</code></pre>
<p>Then after the update, diff the <em>effective</em> config (what the client reports it's using) against
the snapshot. Most clients expose this in the dashboard or via the external controller API:</p>
<pre><code class="language-bash">curl -s http://127.0.0.1:9090/configs | jq .
</code></pre>
<p>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.</p>
<p>I keep a field-by-field reference for these across client versions at
<a href="https://jiedianshouce.com/en/troubleshooting/?utm_source=hashnode&amp;utm_medium=post&amp;utm_campaign=p3">the error-string index</a>
— corrections welcome, especially for clients I don't run.</p>
]]></content:encoded></item><item><title><![CDATA[TUN mode says connected but nothing loads — debugging five layers in order]]></title><description><![CDATA[TUN mode says connected but nothing loads. A five-layer checklist - interface, DNS, routing table, rules, MTU - to isolate the layer that broke.]]></description><link>https://jiedianshouce.hashnode.dev/tun-mode-says-connected-but-nothing-loads-debugging-five-layers-in-order</link><guid isPermaLink="true">https://jiedianshouce.hashnode.dev/tun-mode-says-connected-but-nothing-loads-debugging-five-layers-in-order</guid><category><![CDATA[networking]]></category><category><![CDATA[debugging]]></category><category><![CDATA[Linux]]></category><dc:creator><![CDATA[dong liu]]></dc:creator><pubDate>Tue, 17 Nov 2026 07:20:27 GMT</pubDate><content:encoded><![CDATA[<p>"TUN mode is connected but nothing loads" is one symptom with five different causes, which is why
threads about it go in circles. Each layer fails identically from the user's point of view: the
toggle is on, the status says connected, every request times out.</p>
<p>The layers are ordered by frequency and by cost-to-check, so going top-down finds the fault
faster than any other order.</p>
<h3>Layer 1 — did the interface actually come up</h3>
<p>Creating a virtual network adapter requires elevated privileges. If the background service isn't
installed or was started without admin/root, the core runs in userspace, reports "connected" in
the UI, and never creates an adapter.</p>
<pre><code class="language-bash"># Linux / macOS
ip link show | grep -i -E "tun|utun|mihomo"
ifconfig | grep -A2 utun

# Windows
ipconfig | findstr /i "Mihomo utun"
</code></pre>
<p>You want an interface holding an address in <code>198.18.0.0/16</code> or <code>172.19.0.0/16</code>.</p>
<p><strong>If there's no interface, stop.</strong> Nothing below matters. This is a permissions problem, and no
amount of config editing will fix it. On Windows that means the service component; on Linux it
means the binary needs <code>CAP_NET_ADMIN</code>.</p>
<h3>Layer 2 — is traffic entering the tunnel</h3>
<p>Interface exists but packets still leave through the physical NIC. Usually a competing default
route from another VPN client, Hyper-V, WSL2, or Docker.</p>
<pre><code class="language-bash">traceroute 1.1.1.1    # first hop should be the TUN gateway
route print           # Windows: check the metric on 0.0.0.0
ip route get 1.1.1.1  # Linux: which interface wins
</code></pre>
<p>First hop = your router's LAN IP means the route wasn't taken over. Two TUN drivers on one
machine is a coin flip; uninstall the other one rather than fighting route metrics.</p>
<h3>Layer 3 — DNS</h3>
<p>The most common after permissions, and the most misdiagnosed. The tell: nothing resolves, but a
raw IP works in the browser.</p>
<pre><code class="language-bash">nslookup example.com
ping 1.1.1.1
</code></pre>
<ul>
<li><code>nslookup</code> times out, <code>ping</code> works → DNS isn't going through the tunnel. Either <code>dns.enable</code> is
false, or the client's own DNS override panel is winning over your YAML. Several clients have a
separate override layer that takes precedence and isn't obvious in the UI.</li>
<li>Resolves to a real IP but pages still fail → in fake-ip mode the answer should be <code>198.18.x.x</code>.
A real IP means fake-ip isn't active regardless of what the config says.</li>
<li>Browser's "secure DNS" / DoH enabled → it bypasses the system resolver entirely. Turn it off
before concluding anything about the tunnel.</li>
</ul>
<h3>Layer 4 — the node</h3>
<p>TUN can be perfectly healthy and the node dead. This is the one that makes people reinstall the
client for no reason.</p>
<p>Check the delay test in the dashboard, and open the connections view while loading a page — it
tells you instantly whether the request even reached the core, and which rule matched.</p>
<p>A node that completes a handshake but returns nothing (expired subscription, rotated UUID,
server-side port block) looks exactly like a broken TUN from the browser.</p>
<h3>Layer 5 — the application</h3>
<p>Some apps bypass the system proxy, and a few bypass TUN as well. UWP apps on Windows are
sandboxed and need loopback exemption. Game clients with their own network stack ignore the route
table. Anything with a bundled network library may read its own proxy config.</p>
<pre><code class="language-bash">curl -I https://example.com
</code></pre>
<p>Terminal works, app doesn't → it's the app.</p>
<h3>The part that actually saves time</h3>
<p>Notice that "reinstall the client" doesn't appear in the list, yet it's the most common advice in
every forum thread about this. It's almost never the fix.</p>
<p>The habit that pays off: keep the connections panel open while you reproduce the problem. It
disambiguates layer 4 from layers 1–3 in one glance, which is otherwise the hardest split to make.</p>
<p>Rough split from the cases I've logged: permissions ~30%, DNS ~35%, dead node ~20%, competing
route ~10%, app-level the rest.</p>
<p>Longer writeup with the exact menu paths per client:
<a href="https://jiedianshouce.com/en/articles/clash-verge-rev-tun-not-working/?utm_source=hashnode&amp;utm_medium=post&amp;utm_campaign=p2">jiedianshouce.com</a>.</p>
]]></content:encoded></item><item><title><![CDATA[The 'invalid yaml' error that usually isn't a YAML problem]]></title><description><![CDATA[Clash Verge reports 'invalid yaml' for a remote profile that opens fine in an editor. Four real causes, checked in order, with the fix for each.]]></description><link>https://jiedianshouce.hashnode.dev/the-invalid-yaml-error-that-usually-isn-t-a-yaml-problem</link><guid isPermaLink="true">https://jiedianshouce.hashnode.dev/the-invalid-yaml-error-that-usually-isn-t-a-yaml-problem</guid><category><![CDATA[debugging]]></category><category><![CDATA[tooling]]></category><category><![CDATA[networking]]></category><dc:creator><![CDATA[dong liu]]></dc:creator><pubDate>Tue, 17 Nov 2026 07:19:13 GMT</pubDate><content:encoded><![CDATA[<p>A client shows <code>the remote profile data is invalid yaml</code> and the first instinct is to open the
config and start hunting for a missing space. In my experience that's wrong about nine times out
of ten — the file isn't malformed YAML, it isn't YAML at all.</p>
<p>Here's what's actually happening, and the order I check things now.</p>
<h3>The client saved something that isn't a config</h3>
<p>Most of these clients fetch a config from a URL you give them, then parse whatever came back. If
the URL returns an HTML login page, a 404 page, or a Cloudflare interstitial, the client writes
that HTML into a file named <code>config.yaml</code> and then hands it to the YAML parser. The parser says
"this is invalid yaml" and it's technically correct — HTML is invalid YAML.</p>
<p>The fastest check is to open the exact URL the client fetched, in a browser, logged out. Not the
dashboard, the raw subscription URL.</p>
<ul>
<li>A login form → your token expired. Many providers return a 200 with a login page instead of a
401, so the client has no way to know it failed.</li>
<li><code>&lt;!DOCTYPE html&gt;</code> → an error page or a challenge.</li>
<li>Anything starting with <code>{</code> → a JSON API response, not a subscription.</li>
</ul>
<p>I've seen this happen after a provider rotates their panel hostname: the old URL keeps returning
200, so nothing looks broken, but the body is a redirect notice.</p>
<h3>Then the three real YAML problems</h3>
<p>If the URL genuinely returns a config, these are the ones that actually break parsing, in order of
frequency:</p>
<p><strong>Tab characters.</strong> YAML forbids tabs for indentation. Copy-pasting from a chat app, a PDF, or a
web page silently converts leading spaces to tabs. The error will point at a line that looks
perfectly fine. Fix: search the file for <code>\t</code> rather than reading it.</p>
<p><strong>Full-width punctuation.</strong> If the config was edited on a system with a Chinese IME, a <code>：</code> or <code>，</code>
can end up in the file. YAML treats <code>key：value</code> as a single scalar key, so the block silently
loses its structure and the parser complains several lines later about something unrelated.</p>
<p><strong>A colon inside an unquoted string.</strong> Passwords, SNI values, and <code>path</code> fields often contain
<code>:</code>. In YAML, <code>password: abc:def</code> is a mapping error. It needs quotes. This one is nasty because
it only fails when a password happens to contain a colon, so the same config works for everyone
else.</p>
<h3>The check I run before touching anything</h3>
<pre><code class="language-bash">curl -sL "$SUB_URL" | head -c 200
</code></pre>
<p>If the first 200 bytes aren't <code>port:</code>, <code>mixed-port:</code>, <code>proxies:</code>, or a <code>%YAML</code> directive, stop
debugging YAML. You have a delivery problem, not a syntax problem.</p>
<p>Then:</p>
<pre><code class="language-bash">curl -sL "$SUB_URL" | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin); print('parses')"
</code></pre>
<p>If that succeeds but the client still complains, the client is on a different URL or a cached
copy — check the file timestamp in the profile directory rather than trusting the UI.</p>
<h3>Why I bothered writing this down</h3>
<p>Because the error message is actively misleading. It names the parser, so everyone looks at the
parser. The actual fault is one layer earlier, in whatever replaced your config with a web page.</p>
<p>The full version-by-version notes, including which clients return a 200 on an expired token and
which return a 401, are in a reference I keep at
<a href="https://jiedianshouce.com/en/articles/clash-verge-rev-remote-profile-invalid-yaml/?utm_source=hashnode&amp;utm_medium=post&amp;utm_campaign=p1">jiedianshouce.com</a>.
The short version is above and should be enough for most cases.</p>
<p><em>If you hit a variant of this I haven't covered, drop it in the comments — I'm collecting the
error strings that clients actually emit, and the list is longer than any single doc suggests.</em></p>
]]></content:encoded></item></channel></rss>