The three layers
| Layer | What it does | Typical failure |
|---|---|---|
| Profile | Supplies the configuration the core reads | Empty list, invalid YAML, missing top-level keys |
| Core | Parses the profile, opens local ports, forwards traffic | Rejected field, bind failure, missing Geo data |
| Capture | System proxy or TUN decides what enters the core | Application ignores the proxy; adapter not created |
Diagnose in this order. A capture problem on a core that never started is not a capture problem.
Install from the project
Use the project's own release page and confirm the platform package and architecture. The installer name includes the client version, not the core version — they are separate, and error messages often refer to the core.
Profiles: what “updated” means
- Remote subscription: a URL the client fetches. Update refetches it.
- Local file: a YAML you supply. Updating a subscription does not touch it.
- Active profile: the one the core reads. A profile can exist without being active.
- Overrides: merge rules, scripts and filters applied after download. They can empty a working list.
“Update succeeded” refers to the fetch. It says nothing about parsing, activation or overrides, which is why the four states above have to be checked separately.
Service mode and TUN
TUN creates a virtual adapter and changes routing. The operating system does not permit that from an ordinary user process, so the client installs a privileged helper. When that installation fails, the error appears before any adapter exists — a service problem, not a routing problem.
Order for a first setup:
- Import the profile and confirm it is active with a non-empty proxy list.
- Enable the system proxy and verify one real HTTPS request.
- Only then install the service and enable TUN, if you need broader capture.
- Record the pre-TUN DNS and route state so you can restore it.
Reading the first error
| Message | Layer | Next step |
|---|---|---|
the remote profile data is invalid yaml | Parse | Check what the address returned; an HTML page parses as neither YAML nor a profile |
Missing proxies / proxy-providers | Parse, semantic | Confirm the format matches the client |
invalid domain in dns.fake-ip-filter | Config validation | Find the entry; a wildcard inside a label is illegal |
| Service install failed | Privileged helper | Read the service log; do not run the client elevated permanently as a workaround |
address already in use | Port bind | Identify the listener before terminating anything |
Verify
- One HTTPS request through the intended path, with the result recorded.
- Observed exit address, if region matters.
- Core and client versions, written down — most later questions depend on them.
- Whether the same request works with TUN disabled, which separates capture from forwarding.
Scope
This page describes setup order and the meaning of the common failure messages. Menu names follow the installed version. Nothing here evaluates a provider or guarantees compatibility with any particular subscription.