The short version
When the log points at a remote rule-set tag, back up the configuration and any usable cache, record the actual sing-box version, then establish whether the rule file can be fetched from the path currently configured. A first start with no cache and a periodic refresh that used to work are different cases.
Do not delete an entire routing block, disable certificate verification, or wipe the cache just to get the core to start. Each of those changes where traffic goes, which is a larger problem than the one you started with.
Which step failed
| Observation | Check first | Not established yet |
|---|---|---|
| First start, no cache, log names a remote rule set | url, the HTTP client or outbound used for the fetch, network reachability; on 1.14.0+ consider initial_path | That the proxy node is dead |
| The address returns 403, 404, a redirect or HTML | The provider's current address, access restrictions, the actual response body | That HTTP 200 means the body is a rule file |
| File retrieved, but format or version errors follow | format, the real file content, the version that generated it | That renaming the file converts its format |
| It used to start, and a recent refresh fails | Whether a cache still exists, the last successful time, the default update_interval | That a usable cache means this refresh succeeded |
| File updated but routing behaves the same | Whether a route or DNS rule references the tag, whether new connections match it | That a new file timestamp means the rule took effect |
Recover in order
- Keep a state you can return to. Copy the current JSON configuration, the rule files and a masked log summary. Do not publish subscription tokens, node credentials, the full configuration or a private URL with query parameters. On a work device, follow the organisation's network policy first.
- Confirm the version and the failing stage. Run
sing-box versionand find the failing rule-set tag in the actual startup log. The official configuration documentation provides asing-box checkcommand; a passing check only means the static configuration satisfies the checker, not that the remote download works. - Confirm the object is a remote rule set. The documented types are
inline,localandremote; onlyremoteusesurl. A local file usespath. An ordinary subscription update is a different failure class entirely — identify the object before editing any address. - Check the response, then the content. On the same network and download path, record the HTTP status, the final redirect and the beginning of the body. A public file can be checked in an isolated environment; do not submit a private address to an online checker. A login page, a captcha or an error page means the access condition comes first, before any parser question.
- Check format and version. The documented
formatvalues aresourceandbinary. Compare the actual content against the documentation for the core version you installed. Renaming a file is not a conversion; consult the migration guide for the version in use. - Look for a circular dependency in the fetch path. If the remote rule set must be downloaded through an outbound that itself depends on the rule set that has not loaded yet, prove the fetch path in a separate test configuration. From 1.14.0 the documentation provides
http_clientandinitial_path; the latter supplies verified local content when no cache exists.download_detouris deprecated from 1.14.0, so do not substitute fields without checking the version. - Verify, then accept. Change one factor per attempt and confirm four things separately: the config check, the remote fetch, a successful parse, and the actual route taken by a target connection. Restore the backup on failure. “The process starts” is not the finish line.
Cache behaviour worth knowing
With experimental.cache_file.enabled, remote rule sets are cached. An empty update_interval defaults to one day, so the absence of a new request within a few minutes is not automatically a fault. Public issue #4073 discussed startup failure when a remote rule is unreachable on a cold start; that proposal was closed as not planned, so it documents that someone reported the scenario and nothing more.
Scope and limits
This sequence addresses rule sets handled by the sing-box core. Graphical clients may use different configuration directories, cache locations or core versions, and their interface is the authority. This page performs no connectivity tests against any particular system, carrier or rule repository, and does not promise that a given initial_path or HTTP client resolves your specific error. If the fault sits in ordinary nodes, the system proxy or TUN, use the connection checklist instead.
What to record
sing-box versionoutput and the failing rule-set tag.- The configured
url, recorded as domain plus a masked path. - HTTP status, final redirect and the first bytes of the response.
- Whether a cache exists, its timestamp, and the last successful start.
formatin use and whether the file matches it.- Whether
http_client,initial_pathor a deprecated detour field is present. - What changed between the last working start and this one.