Node HandbookNODE HANDBOOK中文
sing-box · rule-set

sing-box fails at startup on a remote rule-set

When the log points at a rule-set tag, the useful distinction is whether this is a first start with no cache or a refresh that used to work. They fail for different reasons and need different fixes.

Node Handbook editorial team ·

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

ObservationCheck firstNot established yet
First start, no cache, log names a remote rule seturl, the HTTP client or outbound used for the fetch, network reachability; on 1.14.0+ consider initial_pathThat the proxy node is dead
The address returns 403, 404, a redirect or HTMLThe provider's current address, access restrictions, the actual response bodyThat HTTP 200 means the body is a rule file
File retrieved, but format or version errors followformat, the real file content, the version that generated itThat renaming the file converts its format
It used to start, and a recent refresh failsWhether a cache still exists, the last successful time, the default update_intervalThat a usable cache means this refresh succeeded
File updated but routing behaves the sameWhether a route or DNS rule references the tag, whether new connections match itThat a new file timestamp means the rule took effect

Recover in order

  1. 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.
  2. Confirm the version and the failing stage. Run sing-box version and find the failing rule-set tag in the actual startup log. The official configuration documentation provides a sing-box check command; a passing check only means the static configuration satisfies the checker, not that the remote download works.
  3. Confirm the object is a remote rule set. The documented types are inline, local and remote; only remote uses url. A local file uses path. An ordinary subscription update is a different failure class entirely — identify the object before editing any address.
  4. 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.
  5. Check format and version. The documented format values are source and binary. 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.
  6. 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_client and initial_path; the latter supplies verified local content when no cache exists. download_detour is deprecated from 1.14.0, so do not substitute fields without checking the version.
  7. 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 version output 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.
  • format in use and whether the file matches it.
  • Whether http_client, initial_path or a deprecated detour field is present.
  • What changed between the last working start and this one.