<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: dong liu</title>
    <description>The latest articles on DEV Community by dong liu (@dong_liu_359083387a3f9025).</description>
    <link>https://dev.to/dong_liu_359083387a3f9025</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4248231%2F381ea629-e19a-4974-8b3f-0b4edb808355.png</url>
      <title>DEV Community: dong liu</title>
      <link>https://dev.to/dong_liu_359083387a3f9025</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/dong_liu_359083387a3f9025"/>
    <language>en</language>
    <item>
      <title>Six config fields that break after a proxy client update</title>
      <dc:creator>dong liu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 17:44:29 +0000</pubDate>
      <link>https://dev.to/dong_liu_359083387a3f9025/six-config-fields-that-break-after-a-proxy-client-update-1bic</link>
      <guid>https://dev.to/dong_liu_359083387a3f9025/six-config-fields-that-break-after-a-proxy-client-update-1bic</guid>
      <description>&lt;p&gt;Client updates rename things. Not often, not loudly, and usually without a changelog entry that&lt;br&gt;
says "this will break your config." I've now been bitten by the same six fields enough times to&lt;br&gt;
check them first whenever a working setup stops working after an update.&lt;/p&gt;

&lt;p&gt;None of these are exotic. That's the point — they're common enough that most configs contain&lt;br&gt;
them.&lt;/p&gt;
&lt;h3&gt;
  
  
  1. &lt;code&gt;mixed-port&lt;/code&gt; vs &lt;code&gt;port&lt;/code&gt; + &lt;code&gt;socks-port&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;Older configs declare HTTP and SOCKS on separate ports. Newer cores accept &lt;code&gt;mixed-port&lt;/code&gt; and some&lt;br&gt;
front-ends only read that. If your config has &lt;code&gt;port: 7890&lt;/code&gt; but no &lt;code&gt;mixed-port&lt;/code&gt;, the UI may show&lt;br&gt;
"no proxy configured" while the core is actually listening fine.&lt;/p&gt;

&lt;p&gt;Symptom: the client works, but nothing routes through it.&lt;br&gt;
Fix: add &lt;code&gt;mixed-port: 7890&lt;/code&gt; and keep the old keys for compatibility.&lt;/p&gt;
&lt;h3&gt;
  
  
  2. &lt;code&gt;dns.enhanced-mode&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;redir-host&lt;/code&gt; and &lt;code&gt;fake-ip&lt;/code&gt; are not interchangeable, and the default flipped at some point in most&lt;br&gt;
client lineages. A config written for &lt;code&gt;redir-host&lt;/code&gt; used under a &lt;code&gt;fake-ip&lt;/code&gt; default resolves&lt;br&gt;
differently, and the failure shows up as "some sites don't load" rather than a clean error.&lt;/p&gt;

&lt;p&gt;This is the single field I've seen cause the most confusing post-update behaviour, because the&lt;br&gt;
config is valid either way — it just does something different.&lt;/p&gt;
&lt;h3&gt;
  
  
  3. &lt;code&gt;allow-lan&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;Defaults to false, and some updates reset it. If you rely on a phone or a TV routing through the&lt;br&gt;
desktop client, the update silently cuts them off while the desktop keeps working.&lt;/p&gt;

&lt;p&gt;Symptom: "it works on my PC but not on my phone" after an update that "changed nothing".&lt;/p&gt;
&lt;h3&gt;
  
  
  4. &lt;code&gt;external-controller&lt;/code&gt; binding
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;127.0.0.1:9090&lt;/code&gt; vs &lt;code&gt;0.0.0.0:9090&lt;/code&gt;. Updates sometimes tighten this to loopback for security,&lt;br&gt;
which breaks any dashboard you access from another machine — including a phone-based dashboard&lt;br&gt;
app. The core is running; the API just isn't reachable.&lt;/p&gt;
&lt;h3&gt;
  
  
  5. &lt;code&gt;geodata-mode&lt;/code&gt; / &lt;code&gt;geosite&lt;/code&gt; paths
&lt;/h3&gt;

&lt;p&gt;Cores differ on whether they read &lt;code&gt;.dat&lt;/code&gt; files or &lt;code&gt;.mmdb&lt;/code&gt;/&lt;code&gt;.mrs&lt;/code&gt; rule sets. After an upgrade that&lt;br&gt;
switches the geo backend, a config pointing at &lt;code&gt;geosite.dat&lt;/code&gt; may fail to load with an error that&lt;br&gt;
mentions neither geo nor the path.&lt;/p&gt;

&lt;p&gt;Symptom: core won't start, error references a file you never touched.&lt;/p&gt;
&lt;h3&gt;
  
  
  6. &lt;code&gt;tun.stack&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;gvisor&lt;/code&gt; vs &lt;code&gt;system&lt;/code&gt; vs &lt;code&gt;mixed&lt;/code&gt;. Default changed across versions, and the wrong choice shows up as&lt;br&gt;
either "connected but slow" or "some apps can't connect at all" — never as a clear failure. On&lt;br&gt;
Linux, &lt;code&gt;system&lt;/code&gt; needs the right kernel modules; &lt;code&gt;gvisor&lt;/code&gt; avoids that but adds latency.&lt;/p&gt;
&lt;h3&gt;
  
  
  The general pattern
&lt;/h3&gt;

&lt;p&gt;Every one of these fails the same way: &lt;strong&gt;the config remains syntactically valid, so the client&lt;br&gt;
loads it without complaint, and the failure appears somewhere else entirely.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That's what makes updates feel random. The parser has nothing to complain about.&lt;/p&gt;
&lt;h3&gt;
  
  
  A habit worth adopting
&lt;/h3&gt;

&lt;p&gt;Before updating, snapshot the whole profile directory, not just &lt;code&gt;config.yaml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cp -a ~/.config/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;client&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; ~/.config/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;client&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;.bak-&lt;span class="nv"&gt;$(&lt;/span&gt;date +%F&lt;span class="o"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then after the update, diff the &lt;em&gt;effective&lt;/em&gt; config (what the client reports it's using) against&lt;br&gt;
the snapshot. Most clients expose this in the dashboard or via the external controller API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -s http://127.0.0.1:9090/configs &lt;span class="o"&gt;|&lt;/span&gt; jq .
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Nine times out of ten the diff shows one of the six fields above changed, and you're done in two&lt;br&gt;
minutes instead of an afternoon.&lt;/p&gt;

&lt;p&gt;I keep a field-by-field reference for these across client versions at&lt;br&gt;
&lt;a href="https://jiedianshouce.com/en/troubleshooting/?utm_source=devto&amp;amp;utm_medium=post&amp;amp;utm_campaign=p3" rel="noopener noreferrer"&gt;the error-string index&lt;/a&gt;&lt;br&gt;
— corrections welcome, especially for clients I don't run.&lt;/p&gt;

</description>
      <category>tooling</category>
      <category>debugging</category>
      <category>opensource</category>
    </item>
    <item>
      <title>TUN mode says connected but nothing loads — debugging five layers in order</title>
      <dc:creator>dong liu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 17:38:15 +0000</pubDate>
      <link>https://dev.to/dong_liu_359083387a3f9025/tun-mode-says-connected-but-nothing-loads-debugging-five-layers-in-order-522j</link>
      <guid>https://dev.to/dong_liu_359083387a3f9025/tun-mode-says-connected-but-nothing-loads-debugging-five-layers-in-order-522j</guid>
      <description>&lt;p&gt;"TUN mode is connected but nothing loads" is one symptom with five different causes, which is why&lt;br&gt;
threads about it go in circles. Each layer fails identically from the user's point of view: the&lt;br&gt;
toggle is on, the status says connected, every request times out.&lt;/p&gt;

&lt;p&gt;The layers are ordered by frequency and by cost-to-check, so going top-down finds the fault&lt;br&gt;
faster than any other order.&lt;/p&gt;
&lt;h3&gt;
  
  
  Layer 1 — did the interface actually come up
&lt;/h3&gt;

&lt;p&gt;Creating a virtual network adapter requires elevated privileges. If the background service isn't&lt;br&gt;
installed or was started without admin/root, the core runs in userspace, reports "connected" in&lt;br&gt;
the UI, and never creates an adapter.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Linux / macOS&lt;/span&gt;
ip link show &lt;span class="o"&gt;|&lt;/span&gt; grep -i -E &lt;span class="s2"&gt;"tun|utun|mihomo"&lt;/span&gt;
ifconfig &lt;span class="o"&gt;|&lt;/span&gt; grep -A2 utun

&lt;span class="c"&gt;# Windows&lt;/span&gt;
ipconfig &lt;span class="o"&gt;|&lt;/span&gt; findstr /i &lt;span class="s2"&gt;"Mihomo utun"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You want an interface holding an address in &lt;code&gt;198.18.0.0/16&lt;/code&gt; or &lt;code&gt;172.19.0.0/16&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If there's no interface, stop.&lt;/strong&gt; Nothing below matters. This is a permissions problem, and no&lt;br&gt;
amount of config editing will fix it. On Windows that means the service component; on Linux it&lt;br&gt;
means the binary needs &lt;code&gt;CAP_NET_ADMIN&lt;/code&gt;.&lt;/p&gt;
&lt;h3&gt;
  
  
  Layer 2 — is traffic entering the tunnel
&lt;/h3&gt;

&lt;p&gt;Interface exists but packets still leave through the physical NIC. Usually a competing default&lt;br&gt;
route from another VPN client, Hyper-V, WSL2, or Docker.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;traceroute 1.1.1.1    &lt;span class="c"&gt;# first hop should be the TUN gateway&lt;/span&gt;
route print           &lt;span class="c"&gt;# Windows: check the metric on 0.0.0.0&lt;/span&gt;
ip route get 1.1.1.1  &lt;span class="c"&gt;# Linux: which interface wins&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;First hop = your router's LAN IP means the route wasn't taken over. Two TUN drivers on one&lt;br&gt;
machine is a coin flip; uninstall the other one rather than fighting route metrics.&lt;/p&gt;
&lt;h3&gt;
  
  
  Layer 3 — DNS
&lt;/h3&gt;

&lt;p&gt;The most common after permissions, and the most misdiagnosed. The tell: nothing resolves, but a&lt;br&gt;
raw IP works in the browser.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;nslookup example.com
ping 1.1.1.1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;nslookup&lt;/code&gt; times out, &lt;code&gt;ping&lt;/code&gt; works → DNS isn't going through the tunnel. Either &lt;code&gt;dns.enable&lt;/code&gt; 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.&lt;/li&gt;
&lt;li&gt;Resolves to a real IP but pages still fail → in fake-ip mode the answer should be &lt;code&gt;198.18.x.x&lt;/code&gt;.
A real IP means fake-ip isn't active regardless of what the config says.&lt;/li&gt;
&lt;li&gt;Browser's "secure DNS" / DoH enabled → it bypasses the system resolver entirely. Turn it off
before concluding anything about the tunnel.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  Layer 4 — the node
&lt;/h3&gt;

&lt;p&gt;TUN can be perfectly healthy and the node dead. This is the one that makes people reinstall the&lt;br&gt;
client for no reason.&lt;/p&gt;

&lt;p&gt;Check the delay test in the dashboard, and open the connections view while loading a page — it&lt;br&gt;
tells you instantly whether the request even reached the core, and which rule matched.&lt;/p&gt;

&lt;p&gt;A node that completes a handshake but returns nothing (expired subscription, rotated UUID,&lt;br&gt;
server-side port block) looks exactly like a broken TUN from the browser.&lt;/p&gt;
&lt;h3&gt;
  
  
  Layer 5 — the application
&lt;/h3&gt;

&lt;p&gt;Some apps bypass the system proxy, and a few bypass TUN as well. UWP apps on Windows are&lt;br&gt;
sandboxed and need loopback exemption. Game clients with their own network stack ignore the route&lt;br&gt;
table. Anything with a bundled network library may read its own proxy config.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -I https://example.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Terminal works, app doesn't → it's the app.&lt;/p&gt;

&lt;h3&gt;
  
  
  The part that actually saves time
&lt;/h3&gt;

&lt;p&gt;Notice that "reinstall the client" doesn't appear in the list, yet it's the most common advice in&lt;br&gt;
every forum thread about this. It's almost never the fix.&lt;/p&gt;

&lt;p&gt;The habit that pays off: keep the connections panel open while you reproduce the problem. It&lt;br&gt;
disambiguates layer 4 from layers 1–3 in one glance, which is otherwise the hardest split to make.&lt;/p&gt;

&lt;p&gt;Rough split from the cases I've logged: permissions ~30%, DNS ~35%, dead node ~20%, competing&lt;br&gt;
route ~10%, app-level the rest.&lt;/p&gt;

&lt;p&gt;Longer writeup with the exact menu paths per client:&lt;br&gt;
&lt;a href="https://jiedianshouce.com/en/articles/clash-verge-rev-tun-not-working/?utm_source=devto&amp;amp;utm_medium=post&amp;amp;utm_campaign=p2" rel="noopener noreferrer"&gt;jiedianshouce.com&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>networking</category>
      <category>debugging</category>
      <category>linux</category>
    </item>
    <item>
      <title>The 'invalid yaml' error that usually isn't a YAML problem</title>
      <dc:creator>dong liu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 17:38:12 +0000</pubDate>
      <link>https://dev.to/dong_liu_359083387a3f9025/the-invalid-yaml-error-that-usually-isnt-a-yaml-problem-npj</link>
      <guid>https://dev.to/dong_liu_359083387a3f9025/the-invalid-yaml-error-that-usually-isnt-a-yaml-problem-npj</guid>
      <description>&lt;p&gt;A client shows &lt;code&gt;the remote profile data is invalid yaml&lt;/code&gt; and the first instinct is to open the&lt;br&gt;
config and start hunting for a missing space. In my experience that's wrong about nine times out&lt;br&gt;
of ten — the file isn't malformed YAML, it isn't YAML at all.&lt;/p&gt;

&lt;p&gt;Here's what's actually happening, and the order I check things now.&lt;/p&gt;
&lt;h3&gt;
  
  
  The client saved something that isn't a config
&lt;/h3&gt;

&lt;p&gt;Most of these clients fetch a config from a URL you give them, then parse whatever came back. If&lt;br&gt;
the URL returns an HTML login page, a 404 page, or a Cloudflare interstitial, the client writes&lt;br&gt;
that HTML into a file named &lt;code&gt;config.yaml&lt;/code&gt; and then hands it to the YAML parser. The parser says&lt;br&gt;
"this is invalid yaml" and it's technically correct — HTML is invalid YAML.&lt;/p&gt;

&lt;p&gt;The fastest check is to open the exact URL the client fetched, in a browser, logged out. Not the&lt;br&gt;
dashboard, the raw subscription URL.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;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.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;!DOCTYPE html&amp;gt;&lt;/code&gt; → an error page or a challenge.&lt;/li&gt;
&lt;li&gt;Anything starting with &lt;code&gt;{&lt;/code&gt; → a JSON API response, not a subscription.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I've seen this happen after a provider rotates their panel hostname: the old URL keeps returning&lt;br&gt;
200, so nothing looks broken, but the body is a redirect notice.&lt;/p&gt;
&lt;h3&gt;
  
  
  Then the three real YAML problems
&lt;/h3&gt;

&lt;p&gt;If the URL genuinely returns a config, these are the ones that actually break parsing, in order of&lt;br&gt;
frequency:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Tab characters.&lt;/strong&gt; YAML forbids tabs for indentation. Copy-pasting from a chat app, a PDF, or a&lt;br&gt;
web page silently converts leading spaces to tabs. The error will point at a line that looks&lt;br&gt;
perfectly fine. Fix: search the file for &lt;code&gt;\t&lt;/code&gt; rather than reading it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Full-width punctuation.&lt;/strong&gt; If the config was edited on a system with a Chinese IME, a &lt;code&gt;：&lt;/code&gt; or &lt;code&gt;，&lt;/code&gt;&lt;br&gt;
can end up in the file. YAML treats &lt;code&gt;key：value&lt;/code&gt; as a single scalar key, so the block silently&lt;br&gt;
loses its structure and the parser complains several lines later about something unrelated.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A colon inside an unquoted string.&lt;/strong&gt; Passwords, SNI values, and &lt;code&gt;path&lt;/code&gt; fields often contain&lt;br&gt;
&lt;code&gt;:&lt;/code&gt;. In YAML, &lt;code&gt;password: abc:def&lt;/code&gt; is a mapping error. It needs quotes. This one is nasty because&lt;br&gt;
it only fails when a password happens to contain a colon, so the same config works for everyone&lt;br&gt;
else.&lt;/p&gt;
&lt;h3&gt;
  
  
  The check I run before touching anything
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -sL &lt;span class="s2"&gt;"$SUB_URL"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; head -c 200
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;If the first 200 bytes aren't &lt;code&gt;port:&lt;/code&gt;, &lt;code&gt;mixed-port:&lt;/code&gt;, &lt;code&gt;proxies:&lt;/code&gt;, or a &lt;code&gt;%YAML&lt;/code&gt; directive, stop&lt;br&gt;
debugging YAML. You have a delivery problem, not a syntax problem.&lt;/p&gt;

&lt;p&gt;Then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -sL &lt;span class="s2"&gt;"$SUB_URL"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; python3 -c &lt;span class="s2"&gt;"import sys,yaml; yaml.safe_load(sys.stdin); print('parses')"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If that succeeds but the client still complains, the client is on a different URL or a cached&lt;br&gt;
copy — check the file timestamp in the profile directory rather than trusting the UI.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why I bothered writing this down
&lt;/h3&gt;

&lt;p&gt;Because the error message is actively misleading. It names the parser, so everyone looks at the&lt;br&gt;
parser. The actual fault is one layer earlier, in whatever replaced your config with a web page.&lt;/p&gt;

&lt;p&gt;The full version-by-version notes, including which clients return a 200 on an expired token and&lt;br&gt;
which return a 401, are in a reference I keep at&lt;br&gt;
&lt;a href="https://jiedianshouce.com/en/articles/clash-verge-rev-remote-profile-invalid-yaml/?utm_source=devto&amp;amp;utm_medium=post&amp;amp;utm_campaign=p1" rel="noopener noreferrer"&gt;jiedianshouce.com&lt;/a&gt;.&lt;br&gt;
The short version is above and should be enough for most cases.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;If you hit a variant of this I haven't covered, drop it in the comments — I'm collecting the&lt;br&gt;
error strings that clients actually emit, and the list is longer than any single doc suggests.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>debugging</category>
      <category>tooling</category>
      <category>networking</category>
    </item>
  </channel>
</rss>
