Xray Core Breaking Changes 2026 and sing-box Checklist

You upgrade one node and the core refuses to start, or it starts and quietly drops a transport your clients rely on. If Xray or sing-box sits inside your panel, your custom client or a white label stack, that is an outage.

The short answer on Xray core breaking changes in 2026: do not read the version number as a compatibility signal, and do not rely on release notes alone. Xray tags are dates, and as of 31 October 2026 most 26.x tags carry a one line pointer instead of a change list. sing-box documents its removals better. So pin the exact version, validate your real config with the project’s own check command, roll out in stages, and keep the old binary ready.

This guide is for operators and product leads. It has a dated table of removals, renames and new defaults for Xray 26.x and sing-box 1.12 to 1.15, then an upgrade checklist. Facts come from the projects’ own pages, linked as we go, and we say where we could not confirm something.

How to Read Xray and sing-box Release Notes in 2026

Xray tags are calendar dates. The Xray release list shows v26.2.6 published on 6 February and v26.10.21 on 21 October. The number tells you when a build was cut, not how risky it is, so a jump from v26.3.27 to v26.7.28 can contain anything.

The harder problem is the notes. We opened all 13 tags from v26.4.13 (13 April 2026) to v26.9.30 (30 September 2026). Twelve hold a single line pointing at another tag, and v26.9.9 has no notes at all. The next release with notes, v26.10.21, says in Chinese that the full notes will follow at the end of the month or early next month. Then v26.10.29 was published on 29 October with no notes on its page. On 31 October Xray published v26.10.31, which its page marks as the latest. It describes an emergency security update that turns MPTCP off by default, and it says v26.10.29 was superseded and is withdrawn. As of 31 October 2026 we found no full change list for the 26.x tags before it.

sing-box is easier to plan around. Its docs carry a changelog, a deprecated features page that states the version of deprecation and of removal, and a migration guide with old and new option names. Those pages give versions but no dates. We took dates from the GitHub release pages and the Go package version listing, which can differ by a day because of time zones.

Xray Core Breaking Changes by Date (26.x)

This table lists only what a release page states for itself. Field names are written as they appear there.

Tag	Date	What changed	Check first
v25.12.8	8 Dec 2025	Router UseIP option removed. REALITY config now errors when a short ID is too long. VLESS inbound reverse proxy UUIDs are rejected for forward proxying by default.	Configs from older templates
v26.1.23	23 Jan 2026	TLS client fields pinnedPeerCertificateChainSha256 and pinnedPeerCertificatePublicKeySha256 replaced by pinnedPeerCertSha256. Hysteria outbound needs "version": 2 in its settings.	Pinning in subscriptions, Hysteria outbounds
v26.2.6	6 Feb 2026	allowInsecure replaced by pinnedPeerCertSha256, and verifyPeerCertInNames renamed verifyPeerCertByName. The notes call allowInsecure removed, but a linked maintainer note says it switches off at 1 June 2026 00:00 UTC. Xray’s own HTTP requests default to a dynamic Chrome User-Agent.	Anything that skips certificate checks
v26.3.27	27 Mar 2026	Hysteria QUIC parameters move into Finalmask quicParams. echForceQuery defaults to full. XHTTP over HTTP/3 defaults to BBR. Windows ARM 32 bit build dropped.	Hysteria configs, ECH settings
v26.4.13 to v26.9.30	Apr to Sep 2026	13 tags, none with a change list of its own.	Your panel’s notes, then test
v26.10.21	21 Oct 2026	Emergency update. Removes three root certificates from the bundled root list. Says v26.10.10 and v26.10.17 are withdrawn.	Do not run the withdrawn tags
v26.10.29	29 Oct 2026	Published with no notes on its page. The v26.10.31 page says it was superseded and is withdrawn.	Do not run the withdrawn tag
v26.10.31	31 Oct 2026	Emergency security update. Turns MPTCP off by default for TCP listeners, and a comment in the source gives a security reason. Says v26.10.29 is withdrawn.	Inbounds that relied on MPTCP, and which tag your panel pins

Two cautions. First, Xray’s TLS documentation says useSystemCA defaults to false, so Xray uses its built in CA list unless you turn it on, and it still describes allowInsecure as deprecated rather than removed. The source reads differently. At v26.2.6 a check on 1 June 2026 00:00 UTC warned before that moment and returned a removed feature error after it, and the source at v26.10.31 returns that error whenever allowInsecure is true. So we read the notes and the maintainer note as one change with a delayed switch off, and the docs wording as behind the code. 3x-ui’s release notes tie a change in this area to v26.10.10, and add that port hopping udphop masks need Xray 26.9.9 or later and XDNS masks in the names and addrs shape need 26.10.10 or later. Xray’s own page for v26.10.10 showed no notes when we opened it, so treat those version details as the panel’s statements until Xray’s full notes arrive.

Second, the v26.10.21 notes give the maintainer’s reason for the emergency update. We did not verify it independently, so this article describes only the actions the page lists. For REALITY and other transport settings, keep one known good test config per transport, as in our REALITY, Xray and AmneziaWG guide.

sing-box 1.12 to 1.15 Breaking Changes by Version

For how the two cores differ, see our Xray vs sing-box comparison. Here we only track what breaks. Dates follow the Go package listing.

In force today (stable releases)

Version	Date	Removed or changed	Check first
1.12.0	4 Aug 2025	Old DNS server formats deprecated: address gives way to type and server. Legacy outbound DNS rule item deprecated for domain_resolver. GeoIP and Geosite removed. Separate inet4_address style TUN fields removed. Go 1.23 needed to build. with_ech build tag removed.	DNS blocks, geo rules, TUN addresses, build scripts
1.13.0	28 Feb 2026	Removed: WireGuard outbound (now an endpoint), block and dns special outbounds, legacy inbound sniff and domain_strategy fields, override_address and override_port on direct outbounds, the TUN GSO option, legacy ECH fields. TCP keep alive default 10 minutes to 5. auto_redirect rejects MPTCP by default. Go 1.24 needed to build.	Any config written for 1.10 or 1.11
1.14.0	31 Aug 2026	Legacy DNS server formats removed. Go 1.25 needed to build. ip_version and query_type in DNS rules now apply to internal lookups, and mixing them with deprecated DNS fields is rejected at startup. Default TUN hijack mode now sets platform DNS. Hysteria2 client imitates Chrome’s QUIC handshake by default.	DNS rules, TUN DNS, Hysteria2 servers
1.14.1 to 1.14.4	14 Sep to 23 Oct 2026	Patch releases. The changelog lists only “Fixes and improvements” for each of them.	Read before pinning

The 1.14.0 notes add that servers using Ed25519 certificates fail the Hysteria2 handshake until disable_chrome_parrot is set. Removal versions in this table come from the deprecated features page, and the details come from the changelog and migration guide.

Announced for removal, with no dates

The docs already list options that go in 1.16.0, and the 1.15 alphas add one for 1.17.0. They give versions, not release dates, so we cannot tell you when. The list may be incomplete: the 1.14.0 changelog also deprecates the Hysteria v1 tuning fields for removal in 1.16.0, and the deprecated page does not list them.

Option	Replacement	Removal
tls.acme inline ACME	certificate_provider	1.16.0
independent_cache, store_rdrc	Remove the first, use store_dns for the second	1.16.0
ip_cidr and ip_is_private without match_response, DNS rule action strategy, rule_set_ip_cidr_accept_empty	evaluate action with match_response	1.16.0
download_detour and the implicit default HTTP client	http_clients, route.default_http_client	1.16.0
TUN stack	New default stack	1.17.0

Alpha only, not settled

1.15.0 is still alpha, at alpha.13 on 23 October 2026. Alpha notes can change before a stable release, so plan around them but do not pin production to them. So far the TUN inbound uses a new TCP/IP stack by default (alpha.3), and HTTP outbounds default to HTTP/2 with fallback to HTTP/1.1 after an HTTP proxy rewrite (alpha.7).

Panels and Clients: Where Version Skew Bites

Your core is rarely alone. A panel generates configs, nodes run them, and client apps read subscriptions. Those are three version numbers, and breakage often lives in the gaps.

3x-ui shows how it plays out. Its v3.10.0 release notes (12 October 2026) say to upgrade every node, not only the master, and that the panel refuses to place a MASQUE inbound on an older node. They also describe migrations on first start that rewrite stored XDNS masks, legacy quicParams.udpHop settings and Shadowsocks 2022 inbounds that used 2022-blake3-chacha20-poly1305. If a migration fails, the panel does not start. Users of the new port hopping and XDNS masks must update their client apps.

The same notes say outbounds to servers signed by a privately installed CA need “Use system CA” enabled, which matches the useSystemCA default described above.

The timeline matters too. v3.10.2 (14 October) names Xray v26.10.10 as its core, which the Xray v26.10.21 notes call withdrawn. v3.11.0 (25 October) moves to v26.10.21. A node on v3.10.0 or v3.10.2 therefore ships with a core tag its maintainers withdrew, unless you replaced the core yourself. Other panels have their own notes, so read each one rather than assuming they match.

Upgrade Checklist: Pin, Validate, Stage, Roll Back

1. Inventory versions. Record the core version on every node (xray version prints it for Xray), the panel version, and the core inside each client app you ship. Note which component generates the config.
2. Pin exact versions. Use the full tag, such as v26.10.21 or 1.14.4, never “latest”. With a pin you decide when to move, including off a tag the maintainers later withdraw.
3. Read the right pages. For Xray, read the tag you move to, every tag between, any pointer lines they contain, and your panel’s notes. For sing-box, read the changelog, deprecated page and migration guide for each minor version you cross.
4. Run the check command on the real config. With the new binary, run xray run -test -c config.json, which the docs describe as testing the validity of the config files, or sing-box check, pointed at your file with -c as the sing-box docs do in their format example. Do it for the config each node type really receives, since panels can generate different configs per node. A pass shows the config loads, not that a client can connect.
5. Test real handshakes on a canary. A config can parse and still fail on the wire. Connect a real client, over each protocol you offer, from outside your own network.
6. Stage the rollout. One canary node, then a small slice, then a region, then the rest. Write the stop conditions before you start, so nobody decides them mid incident.
7. Test version skew both ways. Try old clients against upgraded servers and new clients against old servers, for every protocol in use. If your panel asks for all nodes at one version, follow it.
8. Keep a rollback you have practised. Keep the previous binary, the previous config and a copy of the panel database, since migrations can block a start. Run the rollback once on the canary. An untried rollback is a guess.
9. Watch handshakes after the change. Ping tells you a host is up, not that a protocol works. TunnelHQ runs real protocol handshakes and turns failed checks into incidents, per its product page, and our guide to monitoring a VPN server fleet covers the wider setup.
10. Calendar the announced removals. sing-box 1.16.0 and 1.17.0 have no dates. Re read the deprecated page on every release.

FAQ

What does an Xray version like v26.10.21 mean?

It reads as year, month and day, so v26.10.21 was cut on 21 October 2026. It says nothing about compatibility, so a newer number may still be a breaking change.

Which Xray version should I run right now?

The one you have tested against your own configs. As of 31 October 2026 the newest published release is v26.10.31, an emergency security update that turns MPTCP off by default and says v26.10.29 is withdrawn. The release before those with notes is v26.10.21, which calls v26.10.10 and v26.10.17 withdrawn, so avoid those two and v26.10.29.

How do I test a config before upgrading?

Run the new binary’s own check against the config the node really uses: xray run -test -c config.json for Xray, sing-box check for sing-box. Then connect a real client to a canary node, because a config can pass the check and still fail on the wire.

Will my sing-box 1.13 config load on 1.14?

Not necessarily. The deprecated features page lists legacy DNS server formats as removed in 1.14.0, and the changelog says some DNS rule combinations are now rejected at startup. Run the check command with the 1.14 binary first.

Do all nodes need the same core version as the panel?

For 3x-ui, its v3.10.0 notes say to upgrade every node, not only the master. For other panels, check their notes, and test mixed versions in staging.

The Takeaway

Xray core breaking changes are manageable if you treat each upgrade as a config compatibility test, not a version bump. Three habits reduce the risk: exact pins, a check command run on the configs your panel really generates, and a rollback you have already practised.

Running Xray or sing-box in production and wary of the next upgrade? DigitalD.tech can review your pinning, testing and rollback plan, and build protocol checks around your own configs. Tell us about your stack on the contact page.

Last checked against the Xray release pages and documentation, the sing-box docs, the 3x-ui release pages and the Go package version listing on 30 October 2026.