The objects that matter
| Object | Role | Typical error |
|---|---|---|
inbounds | How traffic enters (TUN, mixed, SOCKS) | Port in use, unsupported field |
outbounds | Where traffic leaves | Unknown field, unsupported protocol |
route | Rules and the final outbound | Reference to a missing tag |
dns | Resolvers and their routing | Unreachable resolver, circular reference |
route.rule_set | Rule sources: inline, local, remote | Fetch 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
- Confirm the version (
sing-box version) and find the failing object in the log. - Run the configuration check the documentation provides. A pass means the static structure is acceptable; it does not test any network fetch.
- 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.
- If the failure is a field, compare it against the documentation for your version.
- 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.