DEV Community

dong liu
dong liu

Posted on Originally published at jiedianshouce.com

The 'invalid yaml' error that usually isn't a YAML problem

A client shows the remote profile data is invalid yaml 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.

Here's what's actually happening, and the order I check things now.

The client saved something that isn't a config

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 config.yaml and then hands it to the YAML parser. The parser says
"this is invalid yaml" and it's technically correct — HTML is invalid YAML.

The fastest check is to open the exact URL the client fetched, in a browser, logged out. Not the
dashboard, the raw subscription URL.

  • 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.
  • <!DOCTYPE html> → an error page or a challenge.
  • Anything starting with { → a JSON API response, not a subscription.

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.

Then the three real YAML problems

If the URL genuinely returns a config, these are the ones that actually break parsing, in order of
frequency:

Tab characters. 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 \t rather than reading it.

Full-width punctuation. If the config was edited on a system with a Chinese IME, a : or ,
can end up in the file. YAML treats key:value as a single scalar key, so the block silently
loses its structure and the parser complains several lines later about something unrelated.

A colon inside an unquoted string. Passwords, SNI values, and path fields often contain
:. In YAML, password: abc:def 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.

The check I run before touching anything

curl -sL "$SUB_URL" | head -c 200
Enter fullscreen mode Exit fullscreen mode

If the first 200 bytes aren't port:, mixed-port:, proxies:, or a %YAML directive, stop
debugging YAML. You have a delivery problem, not a syntax problem.

Then:

curl -sL "$SUB_URL" | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin); print('parses')"
Enter fullscreen mode Exit fullscreen mode

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.

Why I bothered writing this down

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.

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
jiedianshouce.com.
The short version is above and should be enough for most cases.

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.

Top comments (0)