This article explains how to import nodes into sing-box, troubleshoot subscription links that aren’t recognized and connections that fail after import, and help team members reduce frequent changes to their account’s network environment. Menu names and supported formats vary across sing-box graphical clients. Before proceeding, check the node format; don’t assume every link should be imported as a configuration file.
1. Check the client and node format before importing
sing-box is a proxy core. Most users should choose a graphical client from a trusted source and check its system requirements and maintenance status. The command-line core has no standard “scan QR code to import” interface. Support for subscriptions, QR codes, or single-node links depends on the specific graphical client.
First, check whether the node you received is a subscription URL, a single-node share link, or a complete sing-box JSON configuration. Support for protocols such as VLESS does not necessarily mean a client can directly import the corresponding share link. Clash YAML configurations also cannot be assumed to work as sing-box configurations.
2. Import nodes using a subscription link
- Install and open the client, then go to “Configuration,” “Profiles,” or “Subscription Management.”
- Select “Add Configuration” or “Import from URL,” and enter an easy-to-recognize name, such as “Work.”
- Paste the subscription URL provided by the node provider. Check for extra spaces, line breaks, or missing characters.
- Download or update the configuration. If you see a format-unsupported message, check whether the provider offers a sing-box-specific subscription URL and verify the format required by the client.
- Once the download succeeds, select the configuration, choose a node on the proxy selection page, and start the connection. When prompted, allow the client to create a VPN connection.
- Open a regular webpage to test the connection and check the client logs. Latency test results can help with troubleshooting, but they don’t replace verifying that you can actually access websites.
Subscription links often contain access credentials. Don’t share them in public groups or with unfamiliar conversion websites. If you use free nodes provided by this site, read the format information and availability notes first. Don’t use temporary nodes for important work.
3. Importing single-node links and configuration files
If you received a share link such as vless://, check whether the client has an “Import from clipboard” or “Scan QR code” option. Use it if available. If not, ask the provider for a compatible configuration rather than simply changing the file extension.
If you received a complete sing-box JSON file, select “Import from file” on the configuration page. After importing, run the configuration check provided by the client. If you see a message about unsupported fields or an outdated configuration, check the client version and which versions the configuration supports. Don’t arbitrarily delete unfamiliar fields to get around an error.
4. Team usage and troubleshooting connection failures
For team use, successful import does not guarantee a stable account environment. Frequently switching nodes, egress regions, or devices may trigger security checks on some services. The egress IP address of a shared node may also change. We recommend that team members use clearly assigned configurations. For important accounts, stick to familiar devices and consistent network usage habits, and enable multi-factor authentication.
- Subscription download fails: Check whether the link has expired, whether your current network can reach the subscription URL, and whether your system clock is correct.
- Configuration fails to load: Check the format and version first. Don’t use a Clash configuration as a sing-box JSON file.
- Connected, but webpages won’t load: Check whether the node is working, whether the routing mode meets your needs, and whether the logs show DNS errors.
- Only certain apps have issues: Check for routing rules, whether the app ignores the system proxy, or conflicts with another VPN.
When troubleshooting, change only one setting at a time and keep a backup of any working configuration. When contacting an administrator, provide the client version and redacted logs, and hide subscription URLs, passwords, and tokens.