Node HandbookNODE HANDBOOK中文
sing-box · core

sing-box: reading a configuration by its objects

sing-box is a core with a strict schema. The useful way to read a failure is by object: inbound, outbound, route, DNS, or rule set — because those are the things the parser and the runtime report on.

Node Handbook editorial team ·

The objects that matter

ObjectRoleTypical error
inboundsHow traffic enters (TUN, mixed, SOCKS)Port in use, unsupported field
outboundsWhere traffic leavesUnknown field, unsupported protocol
routeRules and the final outboundReference to a missing tag
dnsResolvers and their routingUnreachable resolver, circular reference
route.rule_setRule sources: inline, local, remoteFetch failure, format mismatch

Why valid JSON fails

JSON syntax and schema validity are two different gates. A file can parse as JSON and still be rejected because a field was renamed, removed in a later version, or given the wrong type. The error usually names the object and the field, and that name is the most useful thing in the message.

When a field is rejected, check the documentation for the version you actually installed, not for the newest release. Migration notes exist precisely because these names change.

Remote rule sets and startup

A rule set declared as type: remote has to be fetched before routing can be constructed. Two situations look similar and are not:

  • First start, no cache: nothing to fall back on, so a failed fetch stops startup.
  • Refresh after a working period: a cache may still be usable, so the behaviour differs.

Do not delete a rule set to get the process to start. That changes which traffic is routed where — a bigger decision than the error you were solving. Back up the configuration, record the failing tag, then check the address, the format and the version.

The order of work

  1. Confirm the version (sing-box version) and find the failing object in the log.
  2. Run the configuration check the documentation provides. A pass means the static structure is acceptable; it does not test any network fetch.
  3. If the failure is a rule set, check the fetch: status, final redirect, and whether the body is a rule file rather than a login page.
  4. If the failure is a field, compare it against the documentation for your version.
  5. Change one item, re-check, and keep the previous configuration for rollback.

Verification is separate from starting

A process that starts is not a working tunnel. After the core runs, confirm: the inbound is listening, a real HTTPS request through it succeeds, and the route the connection took is the one you intended. Three separate observations.

Scope

This page describes the configuration model and a check order. It contains no reproduction on a specific platform, and it does not claim that any third-party subscription is compatible with any particular version.