How to Test a VLESS Config: Six Checks Before You Ship

20 Nov 2026 By ST Muntaha
How to Test a VLESS Config: Six Checks Before You Ship

You have a VLESS link or a client config, and a note from the server side saying it works. A link that imports without an error proves only that an app could read it. The shortest honest way to test a VLESS config is six checks in order: validate the fields, reach the port, match the REALITY or TLS handshake, send a real request and compare the egress IP, measure latency repeatedly from more than one network, and write the result down.

This guide is for operators and app developers. It checks that a config is correct. It cannot say whether a given network will let the traffic through, which depends on the user’s ISP, their network’s filtering, your server IP reputation and ongoing testing. Facts come from the Xray-core and sing-box docs and source, read on 31 October 2026, when the newest Xray-core tag was v26.10.31 and the newest stable sing-box tag was v1.14.4. We did not run the commands on a live server for this article, so try everything on a throwaway server first.

Before You Test a VLESS Config

  • A throwaway server and a test user with its own UUID.
  • The link or config, and read access to the server log.
  • A client you can run locally: Xray-core, or sing-box if your app embeds it, at your server’s version. Field names move between releases (our breaking changes guide tracks them): the current Xray docs call the REALITY public key password, with publicKey as its old name.
  • curl, and a second network to test from.

Treat the link as a credential. VLESS users authenticate by UUID, and the REALITY docs say the client key should not be published openly. Run these checks locally, and do not paste real links into hosted checkers.

Split the link and check each field against the VLESS share link proposal in Xray discussion 716. As of 31 October 2026 it is still a proposal, and a maintainer says the standard may change at any time. Our subscription formats guide covers how apps parse these links.

Field Rule in the proposal
id before the @ Required. Becomes the user id in the config
host and port Required. Port 1 to 65535. IPv6 in brackets
encryption Cannot be empty. none for plain VLESS
security, flow security is none, tls or reality. flow may be empty
fp, sni fp is required with REALITY. sni maps to serverName and cannot be empty
pbk, sid pbk maps to password and is required. sid maps to shortId and may be empty
Whole link No repeated fields. Names are case sensitive. Values escaped

This sketch checks those rules, shape only. It goes further than the proposal in two places: it insists on sni for REALITY, and it applies the key and short id shapes from the Xray docs.

import re, sys
from urllib.parse import urlsplit, parse_qs

u = urlsplit(sys.argv[1].strip())
q = parse_qs(u.query, keep_blank_values=True)
g = lambda k: q.get(k, [""])[0]
bad = []

def need(ok, msg):
    if not ok:
        bad.append(msg)

try:
    port = u.port
except ValueError:
    port = None
need(u.scheme == "vless", "scheme must be vless")
need(u.username, "id missing before the @")
need(u.hostname and port and 1 <= port <= 65535, "host or port missing or invalid")
need(all(len(v) == 1 for v in q.values()), "a field appears twice")
need(q.get("encryption", ["none"])[0], "encryption is empty (write none, or omit it)")
sec = q.get("security", ["none"])[0]
need(sec in ("none", "tls", "reality"), "unknown security value")
if sec == "reality":
    need(g("fp"), "fp is required with reality")
    need(g("sni"), "sni missing: use one of the server's serverNames")
    need(re.fullmatch(r"[A-Za-z0-9_-]{43}", g("pbk")), "pbk is not 43 base64url characters")
    need(re.fullmatch(r"([0-9a-fA-F]{2}){0,8}", g("sid")), "sid must be hex, even length, 16 characters at most")
print("\n".join(bad) or "fields look valid")

It worked when it prints fields look valid. The likeliest miss is a well formed link whose values the server does not hold. Step 3 catches that.

Step 2: Check That the Port Answers

Xray ships a TLS probe (its command line docs call it a ping with a TLS handshake) that dials the address, then handshakes once without SNI and once with it. Run it from outside the server’s network:

xray tls ping -ip SERVER_IP SNI:443

Success prints Handshake succeeded with the TLS version and certificate details. The first handshake sends no SNI, so on a REALITY server its result depends on the target. Read the with SNI result first. Failed to dial tcp means nothing answers on that address and port, so fix the listener, the port in the link or the firewall before looking at keys.

The Xray docs say a REALITY server forwards anything that fails authentication to its target, so a plain probe with an allowed SNI should show the target’s certificate. We confirmed this on Xray 26.10.31 with a REALITY server and xray tls ping. On a plain TLS server, check that the certificate’s allowed domains include your SNI.

Step 3: Match the REALITY Fields Against the Server

When the key or short id is wrong, the client receives the target site’s real certificate. A wrong SNI shows instead as an x509 name error, covered in the failure table. In the Xray-core source the client then logs REALITY: received real certificate (potential MITM or redirection). In the REALITY source the server accepts a client only when it sends a TLS 1.3 hello, the SNI is in serverNames, the hello carries an X25519MLKEM768 key share listed before the X25519 one (a rule in Xray-core v26.9.9 and later), the keys match, the client version is inside minClientVer and maxClientVer if set, the clock gap is inside maxTimeDiff if set, and the short id is in shortIds. Anything else is forwarded to the target.

Compare the Fields

The Xray REALITY docs define each field. Compare them one by one:

Client field (Xray, sing-box, link) Must match on the server How to check
password, public_key, pbk Public key of the server privateKey On the server run xray x25519 -i "SERVER_PRIVATE_KEY" and compare the Password (PublicKey) line. Keys are base64url without padding
serverName, server_name, sni One entry in serverNames Exact match. Wildcards are not supported
shortId, short_id, sid One entry in shortIds Hex, even number of characters, up to 16 in Xray. An empty value needs "" in the server list
fingerprint, utls, fp A fingerprint the client core knows Not unsafe with REALITY. sing-box needs uTLS enabled. Xray’s own REALITY test lists only chrome, firefox and safari as known working
flow, id, uuid The same flow and a user id from the server client list Compare character by character

One wrinkle: the sing-box TLS page says a short id has “zero to eight digits”, yet its example has 16 and its source accepts up to 8 bytes. If one config must serve both cores, use an even number of hex characters, 8 or fewer.

Run a Test Client

This sketch comes from the Xray docs and the XTLS/Xray-examples repository:

{
  "log": { "loglevel": "debug" },
  "inbounds": [
    { "listen": "127.0.0.1", "port": 10808, "protocol": "socks", "settings": { "udp": true } }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "tag": "proxy",
      "settings": {
        "address": "SERVER_HOST",
        "port": 443,
        "id": "USER_ID",
        "encryption": "none",
        "flow": "xtls-rprx-vision"
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "fingerprint": "chrome",
          "serverName": "SNI_FROM_SERVER_NAMES",
          "password": "SERVER_PUBLIC_KEY",
          "shortId": "SHORT_ID"
        }
      }
    }
  ]
}

Run xray run -test -c client.json. The docs say -test checks the config without launching the server, and the source prints Configuration OK. on success. Bad values stop here with a named field, such as invalid "shortId" or empty "password". In sing-box the equivalent is sing-box check -c client.json, with the REALITY fields under tls.reality and tls.utls.

Then start it with xray run -c client.json. It worked if the client log shows no received real certificate line once Step 4 sends traffic. If it does, set "show": true inside realitySettings on the throwaway server. The docs say it prints debug information, and the source shows it includes the client version, time and short id the server saw, and the SNI it forwarded. Switch it off afterwards.

Step 4: Send a Real Request and Compare the Egress IP

A matching handshake proves the keys agree, not that traffic flows. Fetch an address echo page through the tunnel and without it:

curl -sS -x socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 15 https://IP_ECHO_URL
curl -sS --connect-timeout 5 --max-time 15 https://IP_ECHO_URL

Replace IP_ECHO_URL with an echo page you trust or a small endpoint on a server you control. Use socks5h, not socks5: the curl manual says socks5h:// lets the proxy resolve the host name, so DNS goes through the tunnel too. The first command should print the server’s public address and the second your own. Also read the server access log. Xray writes lines shaped from CLIENT accepted DESTINATION, and a rejected line carries the reason.

If the address differs from the server’s, check the outbound on the server: the Xray docs say sendThrough matters when the host has several IP addresses. If an app that insists on QUIC fails, note that the docs say xtls-rprx-vision intercepts UDP on port 443, while xtls-rprx-vision-udp443 does not.

Step 5: Measure Latency, Repeat, and Change Vantage Point

One run is noise. Log timings for repeated requests:

for i in $(seq 1 20); do
  curl -s -o /dev/null -x socks5h://127.0.0.1:10808 --max-time 15 \
    -w '%{http_code} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total}\n' \
    https://IP_ECHO_URL
  sleep 30
done

With a proxy, curl’s time_connect only times the hop to your local SOCKS port, so read time_appconnect and time_starttransfer. Keep the median and the worst run rather than the average. Timeouts and any status other than 200 are findings, not noise.

Repeat at different times of day and from at least two networks that are not yours. A pass from your desk says nothing about a user’s network. The cores can probe on a timer too: Xray has burstObservatory, and sing-box has the urltest outbound. For a fleet, TunnelHQ does real protocol handshakes, not just pings, with VLESS and Xray among the protocols, and its free tester checks a single server. Our fleet monitoring guide covers the scheduled version.

Step 6: Record the Result

Write one record per run, because a release counts as tested only if you can show it. Keep the date, time and vantage point, the core version on both ends, the server, port and security mode (no secrets), the result of Steps 1 to 4, the median and worst latency, the egress address seen and the relevant server log lines. Repeat the whole run after every core upgrade, key rotation or IP change.

What Failures Look Like When You Test a VLESS Config

Symptom Likely cause What to check Traced to
received real certificate, or sing-box reality verification failed The server did not authenticate the hello and forwarded it The Step 3 table. Set show on the server: if its log prints hs.c.ClientVer: [1 8 1] before the rejection, the cause is minClientVer; if it prints no AuthKey or ClientVer line, the hello was refused before authentication (the key share) REALITY, Xray and sing-box source
invalid "password", invalid "shortId", too long "shortId" Key not base64url, or short id odd, not hex or over 16 characters Regenerate the key. Standard base64 output (--std-encoding) may contain +, / or = Xray source, docs
unknown "fingerprint", invalid "fingerprint", or sing-box uTLS is required by reality client Unknown value, unsafe, or uTLS not enabled Use a documented value such as chrome Xray and sing-box source
Server log invalid request user id The UUID is not in the client list Compare ids. A custom string id maps to a UUID: xray uuid -i "custom string" Xray source, docs
Server log client flow is empty or not able to use the flow flow differs between client and server user Set the same value on both Xray source
Client error x509: certificate is valid for ..., not your SNI; server log server name mismatch serverName is not in the server’s serverNames Compare them exactly Tested, Xray 26.10.31 and sing-box 1.14.4
Works for you, fails on some devices or later maxTimeDiff (sing-box max_time_difference) with a wrong device clock Compare clocks, or clear the limit while testing REALITY source, docs
Xray client works, sing-box client fails The sing-box REALITY client (v1.14.4) removes the X25519MLKEM768 key share, and Xray servers from v26.9.9 forward such a hello. Or minClientVer is set and the sing-box client writes a fixed 1.8.1 into its hello The server’s Xray-core version. Clear minClientVer on the test server. Set show Our reading of both sources

FAQ

How do I test a VLESS config online?

You can, but a hosted checker receives your credentials, so use a throwaway user and rotate it afterwards. The steps above need no third party except the echo page you choose.

What does a VLESS checker or v2ray config tester actually test?

At most the steps above: syntax, reachability, handshake, a request through the tunnel and timing. None of it shows whether a user’s network will pass the traffic.

The share link format is a proposal, so apps read different fields and defaults. Compare the link with the Step 1 table, then test with the core your app embeds.

Does passing all six steps mean users can connect?

No. It means the config is correct and the server works from the networks you tried. A given user’s result depends on their ISP, their network’s filtering, your IP reputation and ongoing testing.

Takeaway

To test a VLESS config properly, use a real client, send a real request, repeat it from more than one place, and keep the record. A link that merely parses is not a test.

Shipping VLESS to users on networks that filter traffic? We can help you scope the protocol setup and a testing plan to go with it. Tell us about your markets on the contact page.

Last checked against Xray-core v26.10.31 and its docs, XTLS/REALITY, Xray discussion 716, sing-box v1.14.4 docs and source, and the curl manual on 31 October 2026. Every step was rehearsed on 10 November 2026 in throwaway Docker containers with Xray-core 26.10.31 and 26.6.27 and sing-box 1.14.4, using fresh test keys; Xray-core v26.11.9, released 9 November 2026, was not tested.