An error shown by Hiddify is often the result of a problem, not a direct statement of its root cause. The same “connection failed” message can come from client permissions, subscription content, DNS/TLS, or a remote node. The most effective approach is to change one variable at a time and record the result instead of repeatedly switching settings.

Symptoms: choose the relevant guide first

Main symptom	Read first	First boundary to check
Importing shows `Failed to Add Profile`, `Unexpected Connection Error`, or an unrecognized subscription type	Troubleshoot subscription import failures	Link, response content, certificate, and client parsing
Hiddify says it is connected, but websites or apps have no network access	Connected but no internet	Base network, proxy mode, DNS, and node
System proxy works, but VPN/TUN mode fails	TUN mode does not start	Administrator privileges, virtual adapter, and routing conflicts
Existing configuration still works, but refreshing the subscription fails	Subscription update failed	Subscription status, HTTPS, redirects, and server response
The connection works but is slow, reconnects often, or fails only on one network	Slow or frequently disconnecting	Node, access network, DNS, and client version

Two-minute diagnosis

Complete these five steps in order. Do not change DNS, routing, TUN, and the node at the same time:

Record the situation: Note the Hiddify version, operating system, connection mode, exact error, and time. Compare the version with the official Releases.
Check the base network: Disconnect Hiddify and open a site that is normally available directly. If it still fails, repair the Wi-Fi, mobile data, or operating-system network first.
Change the network once: Switch between Wi-Fi and a mobile hotspot. If that restores access, check the local network, DNS, or network-side restrictions first.
Change one device or node: If the same subscription works on another device, the entire service is probably not offline. If changing the node on the same device restores access, the problem is more likely limited to one node.
Compare connection modes: If system proxy works but TUN/VPN does not, go to the TUN troubleshooting guide. If neither mode works, check the subscription and server.

Subscription URLs commonly contain an account token. Never post the complete link, QR code, configuration file, or unredacted log in a forum, chat group, or GitHub Issue.

Troubleshoot by layer

Layer 1: client

Quit the application completely and reopen it. Closing only the window may leave its background process running.
Check the current version and installation source. Preserve any working configuration before upgrading; do not delete your only working configuration first.
Pause other VPNs, proxies, traffic filters, or virtual-adapter software, then run one controlled test.
Restore advanced settings to their defaults and test again. Change individual settings only when a log points to a specific option.
TUN on Windows requires administrator privileges. The official usage guide also says to start the application with administrator or root privileges before enabling TUN.

Layer 2: subscription

Make sure the link was copied in full, has no leading or trailing spaces, and is not a webpage URL mistaken for a subscription URL.
Check whether the account has expired, its traffic quota is exhausted, or its device limit has been exceeded.
If the link returns a login, CAPTCHA, error page, or empty response, the client cannot parse it as a configuration.
Clash, sing-box, and single-node links are different content types. Hiddify supports multiple formats, but the returned content must still be valid; see the official usage guide.

Layer 3: DNS and TLS

Correct the system date, time, and time zone. A significantly incorrect clock can make HTTPS certificate validation fail.
Open the subscription domain in a browser and check for certificate errors. Do not bypass certificate warnings.
If the log contains dns, certificate, TLS handshake, or a domain-resolution failure, test on another network first, then restore the default DNS or use settings explicitly supplied by the provider.
Do not change https:// to http://. The official changelog states that Hiddify 4.x disabled HTTP subscription links because they create security problems. A plaintext subscription can also expose its token and node details. See the official HISTORY.

Layer 4: server

If the same subscription fails on several devices and networks while other subscriptions work, contact that subscription provider first.
Ask the provider to check the subscription domain’s certificate chain, HTTP status, redirects, response format, node availability, and account limits.
Hiddify is a client. It cannot repair a provider’s certificate, an expired token, node congestion, or an offline server.

Verification: confirm the problem is resolved

Do not rely only on the connection button turning green. Complete at least these checks:

The original error does not recur in three consecutive attempts.
The subscription refreshes manually and shows the expected configuration or nodes.
Websites on different domains and commonly used apps work, rather than only one test address.
After disconnecting Hiddify, the system network returns to normal without a stale proxy or route.
Record the state before the change, the one change made, and the result afterward so the test can be reused if the problem returns.

When to contact the provider or submit an Issue

If the same subscription fails on multiple devices and networks, contact the subscription provider first. If the failure is consistently limited to one Hiddify version or operating system while the subscription works in other clients, search the official Issues for the same error before opening a new one.

Include the operating system and version, Hiddify version, installation source, connection mode, shortest reproduction steps, time of occurrence, and redacted logs. Remove personal paths in domains, tokens, UUIDs, server IP addresses, and account-identifying information.

Hiddify Troubleshooting Guide: Connection, Subscription, and TUN Issues