Clash Subscription Formats Explained: YAML, Base64 & Converters Done Right

What Exactly Is a Subscription Link

A subscription link is an HTTP/HTTPS address that your client polls on a schedule. The response contains a batch of node/server information, and sometimes routing rules as well. Once the client fetches this content, it parses out the node list according to an agreed-upon format and writes it into the local config for the proxy engine to use. The key to understanding subscriptions is separating two layers: how a single node is described, and how the whole config file is structured. The former determines how one link is written; the latter determines the shape of the entire subscription file. When people troubleshoot subscription issues, they tend to stare at the link itself and forget to check what structure the client actually expects — that's the most common blind spot in format-related failures.

Clash-family clients (including forks built on the Mihomo core) natively understand structured YAML configs, while proxy providers and self-hosted setups typically generate generic node-sharing links first. Bridging the two requires a conversion step, and how well that step is done directly determines whether subscription updates go smoothly, whether rules stay intact, and whether all nodes make it through.

Breaking Down the Three Main Formats

Native Clash YAML Config

This is the format Clash clients understand most directly. A full file usually includes proxies (node list), proxy-groups (proxy groups), rules (routing rules), and optional fields like dns and tun. Each node is written as a dictionary with fixed field names, for example:

proxies:
  - name: "HK-01"
    type: ss
    server: example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

YAML is extremely sensitive to indentation — a single misplaced space can break parsing for the whole file, and clients often just say "invalid config" without pointing to the exact line. This is one of the most error-prone spots in subscription conversion.

Generic Base64 Node Links

This is the sharing format most proxy providers use. It's typically a line of text starting with ss://, vmess://, or trojan://, followed by a Base64-encoded parameter block that decodes into the server address, port, encryption method, and other fields. A subscription link usually returns a batch of these lines concatenated and Base64-encoded as a whole, so the client or converter first has to decode the outer layer, then parse each node link individually. The upside of this format is broad cross-client compatibility — almost every mainstream tool recognizes it. The downside is it carries no proxy-group or rule info, only node data.

Client-Specific Formats

Some clients extend YAML with their own fields — display styles for groups, icon URLs, custom DNS syntax, and so on. These extra fields are harmless clutter for the native Clash core, but if you take a config exported from Client A and load it straight into Client B, Client B may error out on a field it doesn't recognize, or simply ignore it and silently drop a feature. This is one of the root causes behind "the same subscription breaks when I switch clients."

How Subscription Converters Work

A subscription converter is essentially a format-translation layer. It first requests the original subscription URL to get the node list in Base64 or another format, decodes each entry to extract server, port, protocol, and encryption parameters, then reassembles everything into a YAML config using a template the target client understands — optionally injecting proxy-groups and rules from a preset rule set. The whole process boils down to three steps: fetch the raw content, parse out node fields, and re-render using a template.

When you use a converter, the address you actually paste into your client isn't the original link from your provider — it's a new URL generated by the converter, typically shaped like "converter domain + parameters (the original subscription URL, target format, rule template)." Every time your client refreshes the subscription, it hits this converter URL, and the converter in turn fetches the original subscription in real time, performs the conversion, and returns the result. That means the converter becomes a middle hop in the chain — if it goes down, your subscription refresh fails too, which is a step people often overlook when troubleshooting.

Pay attention to version compatibility when choosing a rule template. Some templates are written for older Clash versions and reference fields that may be deprecated or renamed in newer cores. After importing, proxy groups can end up looking broken without throwing an outright error, which easily gets mistaken for a problem with the subscription itself.

Common Causes of Conversion Failures

Subscription conversion failures generally fall into four categories, ranked from most to least common:

1. The original subscription URL itself is unreachable. The converter needs to fetch the raw content before it can convert anything. If the provider's link has expired, is rate-limited, or requires access from a specific region, the conversion fails outright — and the error usually reads "failed to fetch subscription" rather than anything about formatting.
2. The node protocol isn't supported by the converter. If a newer protocol type hasn't been added to the converter's template library yet, those nodes get silently skipped during parsing, leaving you with noticeably fewer nodes than the original subscription had.
3. The rule template doesn't match the target core version. The template references fields that only exist in newer cores; an older client either errors out or silently ignores the field, and proxy groups or routing rules end up behaving oddly.
4. Special characters aren't escaped properly. If a node's display name contains YAML special characters like colons or quotes and the converter doesn't escape them correctly, it breaks the syntax of the generated file, which causes every subsequent field to fail parsing.

When troubleshooting, check things in this order: first visit the original subscription URL directly to confirm it loads; then compare the node count after conversion against what your provider's dashboard shows; finally inspect the generated YAML for obvious indentation issues or unescaped special characters. Most problems can be pinned down to a specific step within these three checks.

Steps for Migrating a Subscription to a New Client

When switching Clash clients, reusing the same subscription URL usually just works, since mainstream clients all support standard YAML — but watch out for differences in private fields and default proxy-group naming. Here's a recommended workflow:

• Add the subscription to the new client separately first — don't delete the old client's config right away. Keep a working fallback around.
• Once added, manually trigger a subscription update and check that the node count matches the old client.
• Open the proxy groups page and confirm groups and rule sets loaded correctly, especially checking that the auto-latency-test group can actually pick a node.
• If some custom rules seem to be missing, it's most likely because you'd manually added local rules to the old client — those don't travel with the subscription and need to be re-added in the new client.
• Only after everything checks out should you turn off the old client's system proxy or TUN mode, so the two clients don't fight over the network exit at the same time.

If your subscription was generated through a converter, it's better to re-run the original provider's subscription URL through the conversion process to generate a fresh link for the new client, rather than copying over the converted output from your old client — this ensures the new client gets a rule template that actually matches its own version.

Wrapping Up

Subscription format issues look messy at first glance, but they really boil down to three things: how individual nodes are encoded, how the overall config is structured, and whether a converter processed it along the way. When a subscription won't import or breaks after a migration, first figure out which of these three layers is at fault, then work through the checks in this article — most format-related issues can be tracked down and fixed within a few minutes.