Why Does a REALITY Public Key Mismatch Fail?

A REALITY public key mismatch fails because the client needs public-key material that corresponds to the REALITY server's configured privateKey. In current Project X client configuration that material is stored in a field named password; older configurations and interfaces may call the same role publicKey. If the pair does not correspond, the client and server cannot complete the intended REALITY authentication calculation.［1］

The complete VPN guide covers the end-to-end tunnel. Here the question is deliberately narrower: which REALITY key belongs on which side, why an unrelated key fails, and what that failure does not say about TLS certificates or VLESS users.

Key Takeaways

• The server protects privateKey; the client receives only its corresponding public-key material.
• Current client syntax uses password; publicKey is a historical field name, not a second key to configure.
• A correctly formatted but unrelated public key still fails cryptographic agreement.
• Website certificates, serverName, short ID, and VLESS UUID are separate checks.
• Rotate by deriving and distributing a new pair through an authenticated channel, never by copying the private key to clients.

What is the REALITY public key mismatch?

Project X documents a server-side X25519 privateKey and a client-side password whose value is the corresponding public key. The documentation notes that the client field was formerly named publicKey.［1］ A mismatch occurs when the client value was derived from another private key, was copied incorrectly, was decoded under the wrong schema, or was left stale after server rotation.

The server private key must remain on the server. A client does not need it and should never receive it. The client public value is not interchangeable with an arbitrary key of the same length. Cryptographic parsing can succeed while the relationship fails: shape validation answers “is this plausible key material?” whereas authentication needs “does it correspond to this server key?”

Figure key: 1 is the current client password field containing public-key material; 2 represents the X25519 relationship check; 3 is the server-only privateKey. The lines show a configuration relationship, not transmission of the private key or a complete wire transcript.

Why does the REALITY key pair matter?

Public-key systems are designed so that knowing a public key does not reveal its private counterpart. REALITY uses its key material as part of authenticating and protecting the intended handshake. The server's private value and the client's corresponding public value let the two sides calculate compatible results without sending the private key across the network. The REALITY project describes a design based on modified TLS with certificate-free server authentication for authorized clients.［2］

If the client uses public material from Server B while dialing Server A, the calculations diverge even if both servers are healthy. Retrying cannot make unrelated keys correspond. Changing the SNI, target, UUID, or browser settings also cannot repair that mathematical relationship.

This is why a backup restore can create a subtle failure. A server may restore its address and configuration but generate a new REALITY private key; old clients still hold the previous public value. Alternatively, a management panel may show a newly derived public value while an exported profile remains cached. Both values can look valid in isolation.

Why is the client field called password?

The current name is a schema detail. It does not turn the value into a human-memorable password, shared secret, account password, or server private key. Treat documentation for the exact installed version as authoritative. A UI may continue to label the input “public key,” while its generated JSON uses password.

During migration, do not populate both names blindly. Unknown-field handling varies by implementation and version. One client may reject the old name; another import layer may ignore it; a third may retain a stale value while displaying the new one. Inspect the parsed or exported effective configuration after redacting the value.

Location	Current field	Historical label	Required role
REALITY server	privateKey	privateKey	Secret X25519 private material
REALITY client	password	publicKey	Public material corresponding to that server key
TLS-facing name	serverName	SNI-related label	A permitted name coherent with server configuration
REALITY selector	shortId	short ID	One accepted server-list entry
VLESS user	id	UUID	An allowed proxy user identity

Field names are not evidence that every product exposes them. A subscription URI or QR code can also hide the effective mapping, so compare the import output with the authorized source rather than editing a label by intuition.

How is this different from a TLS certificate problem?

A website TLS certificate binds names and public keys under the Web PKI. REALITY's configuration key pair is a different authentication input. The chosen target and serverNames affect the TLS-facing behavior, but the target website's certificate is not the client's REALITY password. Copying a certificate fingerprint or website public key into that field will not derive the server's REALITY public material.

The symptom can overlap because both failures happen during handshake processing. Separate them by evidence: confirm the intended listener received the attempt, verify the exact server key generation and client configuration revision, and then examine server-name and target compatibility. Why a REALITY target site matters covers that separate contract.

A network device can also terminate or block the path before REALITY evaluates any key. No server-side attempt means the public-key hypothesis is premature. An immediate authorized-server rejection after a key rotation makes it stronger, but still does not identify the field without correlated logs or a controlled known-good comparison.

How is it different from short ID and VLESS UUID failures?

The public key, short ID, and UUID can all be described loosely as credentials, but they answer different questions.［3］ The key corresponds to the REALITY server identity material. The short ID must match an accepted REALITY list entry. The UUID must match an allowed VLESS user after the appropriate outer processing reaches that layer.

A profile can therefore pass one check and fail the next. A correct public key with a wrong short ID is still rejected. A successful REALITY stage with a wrong VLESS UUID can fail later. A correct UUID cannot compensate for an unrelated public key because the request never reaches a usable authenticated VLESS session.

What a REALITY short ID does explains the list-membership check. The VLESS and REALITY layer guide shows why diagnosis should preserve the order of checks rather than replacing every value together.

How should keys be generated and rotated?

Use the implementation's documented X25519 generation command on a trusted administrative system. Capture the private value only into the protected server secret store and the derived public value into the authorized client-distribution system. Avoid terminals with shared history, chat, public paste services, screenshots, and monitoring fields that retain command arguments or output.

For a planned rotation, identify all affected endpoints and a rollback window. Deploy the new private key and distribute its derived public value as one controlled change according to the implementation's supported procedure. If the software cannot accept overlapping key pairs, schedule a coordinated cutover rather than inventing an unsupported dual-key schema.

After deployment, read back the effective server configuration without exposing the private value. Confirm the derived public fingerprint and the client revision. Test one authorized client, then expand. Revoke old profile distribution and remove old stored material after the rollback period and evidence retention rules permit it.

Rotation is not complete merely because one client connects. Confirm that stale profiles fail as expected, current profiles reach the intended later stage, and monitoring does not contain literal keys. Record owners, versions, timestamps, and fingerprints rather than secret values.

How do you diagnose a mismatch safely?

Freeze the failed attempt and stop mass editing. Record endpoint, port, client/server versions, time, effective configuration revision, and the first error stage. Confirm basic reachability and that the intended REALITY listener processed the attempt.

Derive or retrieve the authorized public value for the active server private key through the documented tool. Compare a safe fingerprint with the client's effective password value. Check for whitespace, truncation, stale QR/subscription caches, old publicKey imports, wrong server profiles, and accidental reuse of a value from another environment.

If the pair matches, move to the neighboring checks: serverName, short ID, clock, fingerprint option, software compatibility, and then VLESS identity and flow. If the pair does not match, correct only that value through the protected distribution channel and repeat the same bounded test. The VLESS REALITY failure checklist provides the full sequence.

Never “test” by sending the server private key to a client or a support ticket. Never disable authentication to see whether traffic flows. Both actions destroy the boundary being diagnosed and can turn a configuration mistake into credential compromise.

Is a managed VPN app an alternative to key pairs?

If you maintain a REALITY key pair only to reach an ordinary encrypted connection, consider whether a managed service fits better. AethoVPN accounts use an email verification code, and the documented setup is to install the client and choose a location in the app, not to import or compare keys. On a device where the REALITY client fails, a working AethoVPN connection shows that the device can reach the internet through an encrypted tunnel, which keeps attention on the key pair rather than on basic connectivity. Its documentation mentions neither REALITY nor X25519 key import and names no protocol, so the expected public key for your own server still has to come from the authorized configuration owner. Create an account with your email to try the managed route.

Summary

• The client public material must correspond to the active server privateKey.
• Current syntax names the client field password; older material may say publicKey.
• Valid-looking but unrelated keys fail the cryptographic relationship.
• REALITY keys, website certificates, short IDs, and VLESS UUIDs are separate inputs.
• Diagnose with effective-config fingerprints and rotate through protected, version-aware channels.

FAQ

Is the client password a normal password?

No. In current REALITY configuration it carries the server's corresponding public-key material. It is not a human account password or the server private key.

Can I copy the server privateKey to the client?

No. The private key must remain protected on the server. Generate or derive the corresponding public value using the documented tool and distribute only that client value.

Why does an old configuration say publicKey?

That is the historical client field name. Check the installed implementation's current schema and verify the effective imported configuration rather than filling both fields.

Is the REALITY key the target website's certificate key?

No. Website certificate validation and REALITY configuration authentication are distinct. The target's certificate and permitted server name cannot replace the REALITY key pair.

Can a correct UUID fix a public-key mismatch?

No. The VLESS UUID belongs to a later user-authentication layer. It cannot repair an outer REALITY key relationship that fails first.

Does a timeout prove the key is wrong?

No. DNS, routing, address family, firewall, port, or listener failures can occur before key processing. Correlate both endpoints and identify the first broken stage.

Should public-key material be redacted?

Yes in public diagnostics. Although it is not the private key, it is sensitive configuration material that identifies the server profile and should be shared only through authorized channels.

Disclaimer: This article is general technical information for authorized systems. Protect private keys, use authenticated distribution, and do not weaken verification during diagnosis.

Sources:

1. Project X, "REALITY configuration": https://xtls.github.io/en/config/transports/reality.html
2. XTLS, "REALITY README": https://github.com/XTLS/REALITY/blob/main/README.en.md
3. Project X, "VLESS inbound configuration": https://xtls.github.io/en/config/inbounds/vless.html

Sources checked 12 September 2026.

---

Related Articles:

• Map the complete VPN path
• Separate VLESS, REALITY, and XTLS Vision
• Troubleshoot a failed VLESS Reality connection
• Understand the REALITY target contract
• Understand the REALITY short ID