Fixing Mihomo REALITY Authentication Failure: minClientVer

On this page

Author: Independent Clash Client Guide
Published: September 2, 2026
Estimated reading time: About 10 minutes

First confirm that this is the same REALITY compatibility issue

This article covers one specific combination only: the server runs Xray-core v26.7.11 or later, the VLESS inbound uses REALITY, and realitySettings does not explicitly set minClientVer; the client uses the Mihomo core, such as Clash Verge Rev, FlClash, or another Mihomo frontend.

A typical symptom is that the configuration loads and the server port is listening, but the client reports REALITY authentication failed, or the server logs authentication failed or validation criteria not met, while real traffic remains at 0.

If the error mentions x509, certificate, invalid short id, invalid public key, an SNI error, or a normal node timeout, troubleshoot the corresponding field first; those cases are outside this article's direct scope.

Mihomo issue #2967 documents a conflict between session version 1.8.2 and the default threshold. Xray issue #6477 documents that the same configuration failed after the server was upgraded from v26.6.27 to v26.7.11, then worked again after the server version was rolled back.

3x-ui issue #5922 provides corroborating evidence from a panel-managed setup where the connection recovered after explicitly setting a compatible minClientVer.

A recent request in issue #3132 asked for this known boundary to be documented in Mihomo, but the maintainers did not announce a formal client-side fix.

Continue only when all four conditions match

Check	Matches this article	If it does not match
Protocol	VLESS + REALITY	Troubleshoot the actual protocol, TLS, or transport first
Server	Xray-core v26.7.11+	Do not apply this article's version conclusion
Server field	minClientVer is empty or omitted	Compare the explicit value with the client version
Clients	Mihomo core with an authentication failure	Confirm the actual core and the first error

Back up the configuration and record the actual versions on both sides

Before changing the server, export or copy the active Xray configuration. Record the control-panel version, the Xray-core version, the Mihomo version shown by the client, and the time of the first failure. Do not write only "everything is up to date"; exact version numbers are required for a repeatable comparison.

Also record the affected inbound's protocol, network, security, flow, serverNames, shortIds, and whether minClientVer is empty. The backup may contain a UUID, privateKey, subscription identifier, and server address, so keep it in a controlled location and redact any public issue or screenshot.

xray version

Rollback baseline before making changes

The current Xray configuration is backed up in a controlled location
The server's Xray-core version and the client's Mihomo version are recorded
The first client and server errors are saved
The UUID, public key, private key, short-id, and SNI have not been changed
A failed test result from the same network is available

Understand why Xray rejects Mihomo

The official Xray REALITY documentation defines minClientVer as the minimum client version allowed by the server and states that its current default is 26.3.27. Together with the same-configuration reproduction in Xray issue #6477, this shows that starting with v26.7.11 the server applies this default threshold even when the field is empty, instead of continuing to interpret an empty value as unrestricted.

Current implementation evidence in Mihomo issue #2967 shows that its REALITY ClientHello session version is 1.8.2. The server rejects the handshake when it compares 1.8.2 with the default minimum version 26.3.27, so the same node can work in an Xray client and fail in a Mihomo client.

This is not an ordinary certificate check, nor is the client YAML missing a shareable field. minClientVer belongs to the Xray REALITY server inbound configuration and is not delivered to ordinary users through a Clash or Mihomo subscription. If you do not control the server, give the versions and error to the service provider; you cannot invent this field on the client.

The Xray client works, but Mihomo reports REALITY authentication failed

First compare the server's minClientVer with the versions on both sides.

All clients fail

Check the inbound listener, UUID, short-id, SNI, keys, and firewall, not just the versions.

Only one node fails and the server was not upgraded

First check that node's complete REALITY parameters and service status.

The client shows only an x509 or certificate error

Troubleshoot the certificate, time, and SNI instead; do not lower minClientVer.

Run one controlled comparison by changing only the version or threshold

The most useful comparison keeps the same inbound, node, and network while changing only the client core or server version. If an Xray client can complete a real HTTPS request through that inbound while a Mihomo client consistently fails, the port, keys, and target site have not all failed together.

If you retained the official Xray v26.6.27 before upgrading and the same configuration works again immediately after returning to it, that also supports a version-compatibility diagnosis. Use the rollback only for short-term confirmation; do not replace a production server without a backup and an official binary source.

How to interpret the comparison

Comparison result	Next step
The Xray client succeeds and Mihomo fails	Compare minClientVer with the Mihomo session version
Both types of client fail	Return to checking the port, inbound, and REALITY parameters
v26.6.27 succeeds and v26.7.11+ fails	Establish the version boundary before evaluating an explicit compatibility threshold
It works only after changing networks	Check the network path or blocking; do not attribute the result to minClientVer

Decide whether lowering the minimum version is acceptable

The official Xray documentation explicitly warns that lowering minClientVer allows older clients to connect, but their TLS fingerprints differ more noticeably from real browsers and may be easier for DPI to identify. This is a tradeoff between compatibility and detectability, not a cost-free fix.

If you can upgrade to a compatible client that meets the server threshold and has been verified on the same node, prefer to keep the Xray default. If you must continue using the current Mihomo client, explicitly set the minimum to match its reported 1.8.2; do not enter 0 or 0.0.0 or disable every restriction merely for convenience.

If this server is shared, first identify which clients still require the older threshold and record the reason, time, and restoration condition for the change. Change only the affected inbound; do not loosen every REALITY inbound in bulk.

Make the smallest compatibility change on the server

In a panel such as 3x-ui, edit the affected VLESS inbound, open the Security or REALITY settings, and change Min Client Ver from empty to 1.8.2.

When using a native JSON configuration, add minClientVer only inside that inbound's realitySettings. Do not change the UUID, privateKey, serverNames, or shortIds.

After saving, use the current Xray binary to test the actual configuration file first. The official command documentation states that the -test option of the run subcommand validates the configuration without starting the service. The configuration path, binary name, and service restart entry point depend on your installation; for a panel-managed service, prefer the panel's own test and restart workflow.

"streamSettings": {
  "security": "reality",
  "realitySettings": {
    "minClientVer": "1.8.2"
  }
}

xray run -test -config /path/to/config.json

Minimal change sequence

Back up the active configuration
Preserve the original empty value and rollback file. Do not expose the privateKey, UUID, or server address.
Change only one inbound
Explicitly set minClientVer to 1.8.2 and leave all other REALITY parameters unchanged.
Run the configuration test
If the test fails, restore the backup immediately and do not restart with a configuration that contains a syntax error.
Restart through the existing management method
Use the panel or existing service manager; do not start a second Xray instance in parallel.

Verify the handshake and real traffic with the same node

After restarting the service, do not look only at the latency number. Keep the original Mihomo node, SNI, short-id, public key, and client fingerprint unchanged. Retry the HTTPS request that previously failed every time, then inspect the client connection record and server log.

When the fix is effective, REALITY authentication failed no longer appears, the server shows the inbound reaching VLESS processing, the client carries real upstream and downstream traffic, and at least two consecutive HTTPS requests complete. Reimporting the subscription is usually unnecessary because the server's acceptance threshold is what changed.

Verification checklist

The Xray configuration test passes and only one service instance is running
The same Mihomo node no longer reports REALITY authentication failed
The server log no longer sends the connection into the authentication-failure branch
A real HTTPS request returns content, not just a latency reading
Two consecutive retests pass, and the result remains explainable after changing networks
The UUID, keys, SNI, short-id, and skip-cert-verify were not changed

Restore the default and roll back if the risk is unacceptable

If the fingerprint risk from lowering the minimum version is unacceptable, restore the original realitySettings, rerun the configuration test, and restart through the existing management entry point. The older Mihomo client is then expected to fail again; replace it with a verified client that meets the threshold.

If service must be restored in the short term and no compatible client is available, you can consider temporarily returning to the verified official Xray v26.6.27 used before the upgrade, provided that the backup is complete and the source can be verified. This is a compatibility rollback; it does not mean that the older version is safer, and it must not override a later fix. Keep the current version's installation file and recovery plan.

If the connection still fails after explicitly setting 1.8.2, restore the backup immediately and stop lowering the value. Instead, check the configuration actually loaded by the server, the inbound port, UUID, short-id, SNI, keys, and the client's first error.

These actions do not fix the version threshold

Do not enable skip-cert-verify, blindly change the SNI or client-fingerprint, regenerate the UUID, REALITY keys, or short-id, or repeatedly convert the subscription. None of these actions changes the client version compared by the server.

Do not switch every node to Global, disable rules, or delete the local configuration either. Authentication is established after rule routing; when the REALITY server has already rejected the handshake, the client's proxy mode cannot make it pass.

Common incorrect actions

Action	Why it is ineffective or risky
Enable skip-cert-verify	minClientVer is not an ordinary certificate check
Regenerate the UUID and REALITY keys	It breaks the original comparison and still does not change the version threshold
Set minClientVer to 0	It broadens compatibility and fingerprint risk and is not the smallest fix
Treat a recovered latency reading as success	Latency does not mean that real HTTPS traffic has passed

Current evidence boundary and future maintenance

As of 2026-09-02, the official Xray REALITY documentation still lists 26.3.27 as the default minClientVer and explicitly documents the fingerprint risk of lowering it. Mihomo issue #2967 is marked wontfix, and the later documentation request #3132 is also closed, so waiting for a particular Mihomo release cannot be presented as a confirmed fix path.

The available evidence supports the narrowly defined version-compatibility diagnosis in this article, but not every REALITY authentication failed error can be attributed to minClientVer. An invalid short-id, public key, SNI, time, flow setting, port, or server that did not load the new configuration can produce similar symptoms.

Remove this temporary compatibility setting only after an official Xray or Mihomo release, official documentation, or merged code explicitly changes the boundary and a real request succeeds on the same node. The maintenance record should retain the server version, explicit threshold, clients requiring compatibility, and date of the latest verification.

How to Fix Mihomo REALITY authentication failed