Find the stage that failed: profile download/import, service startup, or access after startup. First-time setup is covered in the user guide.
Remote profile download or import failed
Check that the URL is complete, has not expired, and is reachable on the current network. Authentication/HTTP errors need the provider’s access requirements checked; JSON parse errors need the returned format checked. A login page, error page, Clash YAML or node list is not a complete sing-box configuration, even if the download request succeeded.
A saved profile cannot start
Saving and starting are separate steps. Record the core version and first relevant startup error. Unrecognized fields or types point to a format/version check; file or rule-set errors point to their paths/download conditions; tunnel permission errors require platform authorization and VPN conflict checks. Do not delete DNS/routing fields just to suppress an error: that can change traffic behavior.
The service is running but access fails
Stop sing-box and verify basic direct connectivity, then start the same profile and test the intended target. If groups exist, check the selected node. Use logs to distinguish DNS errors, timeouts and authentication failures; when only one app is affected, inspect per-app and routing settings. Change one condition at a time, then repeat the same test. Running state alone does not prove working access.
For a support request, provide OS, client/core versions, failed stage and a redacted error excerpt. Remove remote URL tokens, node passwords and other private values before sharing.
Why are groups or mode controls missing?
Group controls require Selector or URLTest outbounds; mode controls depend on at least two clash_mode values in the configuration. Their absence alone is not an installation failure. Check whether the current profile defines them, then see groups and modes.
Can I use a Clash subscription directly?
Clash YAML cannot be used as sing-box JSON. Prefer the provider’s compatible sing-box output; when conversion is necessary, verify nodes, DNS, routing and the target core version. The label “subscription” alone does not identify the returned format.
Does sing-box support ShadowsocksR?
Current sing-box versions do not support ShadowsocksR; support was removed in 1.6.0. SSR and Shadowsocks are different protocols. Renaming a file or converting its subscription format cannot turn an SSR server into a Shadowsocks server.
How do I replace old GeoIP and Geosite settings?
GeoIP and Geosite were deprecated in 1.8.0 and removed in 1.12.0. Use rule-sets and migrate the rules and references in old configurations; simply renaming the old files does not perform that migration.
Which guide should I start with?
Start with the common user guide. Platform pages cover installation and permissions; the configuration reference and migration guide are for writing parameters or updating old fields.
Is there an official Windows GUI?
Yes. sing-box for Desktop is the official Windows/Linux GUI. GUI for SingBox is a separate third-party client with different controls; the illustrated SFW guide is in Chinese.
Which Windows download should I choose?
Choose the SFW EXE for the official GUI, matching x64, x86 or ARM64. Ordinary sing-box Windows ZIP files contain the command-line core. The official GUI requires Windows 10 or newer; see the platform download page.
Why does a refreshed profile still fail?
A refresh only fetches remote content again. Confirm the update succeeded, select the profile, start, then verify access; refreshed content can still be incompatible or contain an unavailable node. Profile download and connection failures need separate checks.