· Troubleshooting · About 7 min read
Clash Subscription URL Not Working or Import Failing? Troubleshoot Errors
Troubleshoot failed Clash subscription imports, from expired links and incompatible formats to network blocks and YAML errors, with a step-by-step checklist.
First, pinpoint where the import fails
Keep your working configuration before making changes, then open the Clash client’s logs or subscription update details. Run an update manually, note the time, and find the first related error. Importing a subscription involves three steps: fetching the response, parsing the configuration, and loading it in the core. An “Update failed” message could refer to any of them.
| Error or symptom | Check first |
|---|---|
401、403、404 | Account status, URL integrity, and server access restrictions |
no such host、timeout、x509 | DNS resolution, connection route, and certificate trust |
HTTP 200 but the format is reported as invalid | Is the response a configuration, a login page, or a generic proxy list? |
yaml: line 12 or unsupported proxy type | Check YAML structure and supported core features separately |
401, 403, or 404: Check the URL and account status
- Copy the URL again from your provider’s account dashboard. Choose a subscription link labeled for Clash or mihomo. Check the pasted text for quotation marks, line breaks, or trailing spaces. Preserve the original query parameters: don’t edit anything after
?or copy from text that the interface has truncated. - Check the expiration date and token status. Being able to sign in doesn’t mean an old subscription URL is still valid. If you’ve renewed, reset the subscription, or moved to a different service, create a new configuration using the current URL in your dashboard. Replace the old entry only after the new one loads successfully.
- Use the status code to narrow it down.
401usually means authentication failed.403means the request was denied, possibly because of account permissions, request frequency, or gateway rules. A404may mean the URL path has changed, or the server is hiding the resource’s status.429means too many requests. Wait as instructed by your provider instead of retrying repeatedly.
If the URL opens in a browser but the Clash client returns 403, test it in Safari using File → New Private Window. A regular window may include a signed-in session cookie, while subscription updaters typically don’t share browser sessions. The private window may still behave differently from the Clash client, since they can use different request headers and connection routes. If the content is visible only after signing in, ask your provider whether you copied a web page URL instead of a direct subscription link.
Timeouts, DNS failures, and certificate errors: Check your macOS network
Check your current connection and proxy ports
On macOS 13 or later, open System Settings → Network → your current network service → Details → Proxies. Check whether the web proxy and secure web proxy point to addresses that are still listening. For example, if System Settings uses 127.0.0.1:7890 but the Clash client’s current mixed port is 7897, apps that use the system proxy may fail to connect. These ports are examples for troubleshooting; use the values shown in your Clash client.
Whether a subscription updater uses the system proxy depends on the Clash client and its download settings. If updates worked before you changed configurations, switch back to the previous one and test again. If the system proxy or TUN may be affecting the test, change one setting at a time on a network you’re authorized to use, and compare results for the same subscription. Being able to open a page in Safari doesn’t prove the updater can reach it.
Tell DNS errors, timeouts, and TLS errors apart
no such host: Check the domain spelling, then review DNS under Details for your current network service. On public Wi-Fi, make sure you’ve completed the network sign-in process first.i/o timeout: Check whether the error occurs during DNS resolution, connection, or while waiting for a response. If possible, test once on another network you’re authorized to use. If it fails only on one network, check that network’s proxy or access policies instead of resetting the subscription right away.x509: certificate signed by unknown authorityor an expired certificate: Open System Settings → General → Date & Time and confirm the system clock is correct. If the problem persists, contact your network administrator or provider. Don’t disable certificate verification or install root certificates from unknown sources.
HTTP 200 but the import still fails: Check the response format
200 only means the server returned content; it doesn’t mean that content is a configuration. If the Clash client can preview the response, check its opening lines and key fields. If you see <!doctype html>, a sign-in prompt, or a gateway message, find out why you received a web page instead. If you see a JSON error object, start with the server’s error message. Changing the file extension to .yaml won’t change its format.
- Full configuration: Usually includes
proxies:orproxy-providers:, and may also includeproxy-groups:andrules:. Top-level fields and references must match the requirements of the current core. - Data for a proxy provider only: Some YAML files contain only a list of proxies for use with
proxy-providersin an existing configuration. If you have this kind of URL, ask your provider for a full configuration link. Don’t assume it can replace your entire configuration. - Generic proxy subscription: The response may be Base64 text or a line-by-line list of URIs such as
ss://. Whether it can be imported depends on explicit support in your Clash client. Otherwise, use the format provided for that client by your service.
The same URL can return different formats depending on the request headers. If the browser preview doesn’t match the content shown in the logs, use the link your provider recommends for your Clash client. If the logs distinguish between a main configuration URL and a proxy provider URL, identify which one failed: successfully downloading the main configuration doesn’t mean its proxy data updated too.
YAML line numbers and core errors: Troubleshoot separately
If there’s a line number, check indentation and lists first
Open a copy of the configuration in a local plain-text editor. If the log points to line 12, check line 11 and the fields at the same level too. A parser may not spot a missing quote, colon, or list marker until it reads the next item. Use spaces, not tabs, and align fields at the same level. This example shows only the syntax for a rules list, not a complete configuration:
rules:
- DOMAIN,example.com,DIRECT
- MATCH,DIRECT
Remote subscription updates may overwrite manual edits. If the original response has a syntax error, report the line number and error type to your provider after redacting sensitive details. If the error appears only after applying an override, disable the most recently changed override and test the copy again.
If parsing succeeds but loading fails, check the core
unsupported proxy type isn’t an indentation error. It means the current loader doesn’t support a proxy type in the configuration. Find the client and core versions under About in your Clash client or in the startup logs, for example mihomo v1.19.0. The app version shown in the interface isn’t a substitute for the core version. Configurations for Clash Meta (mihomo) may use protocols or fields that older Clash cores don’t recognize. Check them against your provider’s documentation and the core documentation.
If the error says a proxy or policy group can’t be found, check the name references. Targets in rules must match built-in policies, proxies, or policy groups. Proxy names listed in a policy group must also exist. Check whether an override changed a group name without updating the rules. Don’t just delete the line mentioned in the error: removing a final fallback rule or changing a policy can make the configuration load while routing traffic differently.
After fixing the issue, verify updates, loading, and connectivity separately
- Verify the update. Run an update manually and check the entry’s timestamp and logs to distinguish the new response from an old cache. If you use a remote proxy provider, check its update status too.
- Verify the configuration loaded. Select the configuration you just imported and check that the core accepted it and that its proxies and policy groups appear. If the update succeeded but you haven’t switched configurations, the interface may still show the old proxies.
- Verify connectivity. Compare a site expected to connect directly with one expected to use a proxy. Check the connection logs to confirm the rule and outbound route match your expectations. If only a proxy node times out, the issue is now connectivity—not subscription import—and there’s no need to keep changing the subscription URL.
If the issue persists, note your macOS version, Clash client version, core version, update time, HTTP status code, and first redacted error. Also say whether you can reproduce it on another network you’re authorized to use. For connection and traffic-routing issues, see Configuration Troubleshooting.