A WireGuard key mismatch means at least one peer record does not contain the public identity derived from the other side's active private key, or the optional preshared keys differ. Silence alone cannot tell you which side is wrong. Build a two-way public-key mapping from trusted local observations, compare the intended peer records, and rotate or replace material only after identifying the stale edge.

The complete VPN guide covers broader connection stages. This guide focuses only on static WireGuard identity and optional preshared-key agreement.

Key Takeaways

Each side keeps its own private key and configures the other side's public key as a peer identity.［1］

Compare only public keys or controlled fingerprints; never exchange private keys to “check” them.

A wrong endpoint, blocked UDP path, clock-independent routing fault, or wrong AllowedIPs can look like a key failure.

A current handshake proves that the active static-key mapping matched for that peer at that time.

Treat a preshared-key mismatch as a separate secret-state comparison; neither side can safely display its value for visual matching.

How are WireGuard keys mapped?

Every WireGuard interface has a static private key. Its public key is derived mathematically and serves as the interface's identity. A peer stanza stores the remote interface's public key. During the protocol handshake, each side uses its own private key and the configured remote public key; the protocol does not send a negotiable username that can repair an incorrect mapping.［1］

The whitepaper describes peers as associated with public keys and allowed IP addresses.［2］ This gives one interface several independent records: its local identity, the identity expected for each remote peer, and the address prefixes assigned to each peer. A correct public-key pair can still carry no useful data when the address mapping is wrong.

An optional preshared key augments the public-key cryptography. The wg manual exposes configuration fields for private keys, peer public keys, preshared keys, endpoints, allowed IPs, keepalive, and runtime information.［3］ The preshared key must match on both sides, but because it is secret, a safe procedure compares provenance or a locally calculated controlled fingerprint—not the raw value in chat, tickets, screenshots, or command output.

Material on side A	Expected relationship	Material on side B
A active private key	Derives	A observed public key
A peer public key for B	Must equal	B observed public key
B peer public key for A	Must equal	A observed public key
A optional PSK for B	Must be the same secret generation	B optional PSK for A
A `AllowedIPs` for B	Maps destinations to B	Not a key comparison

What evidence supports a WireGuard key mismatch?

A newly imported profile that never handshakes after one side rotated keys is strong contextual evidence. So is a peer record whose public key does not equal the public key derived locally on the intended remote device. A handshake that stopped immediately after a controlled key replacement narrows the change window.

By contrast, repeated initiations without responses are nonspecific. UDP may be blocked, the endpoint may be wrong, NAT state may have expired, the service may not be listening, or the peer may be offline. The server-response handshake guide explains why reachability and authentication evidence must remain separate.

If a fresh handshake exists for the exact peer record, its active static keys and optional PSK agreed at that time. A later data failure belongs first in the no-data counter workflow, not in speculative key rotation.

Seven-step key check

Step 1: Label the two endpoints before reading keys

Give each endpoint an unambiguous operational label, such as laptop-2026 and gateway-east, and record who administers it. Note the intended interface, peer stanza, endpoint, and client address without copying the complete configuration. Many “mismatches” are actually comparisons between an old device record and a newly enrolled device with a similar display name.

Freeze the time of the failed attempt and the latest-handshake value for the intended peer on both sides. If several peers share the same gateway, identify the record by its public key and assigned address prefix rather than by list position.

Do not rename, delete, or regenerate anything during inventory. A changed key destroys the evidence needed to decide whether the configuration distribution, active process, or peer record was stale.

Step 2: Derive each local public identity in place

On side A, use the platform's trusted WireGuard tooling to derive or display the public key corresponding to the private key that the active interface actually uses. Store only the public result in the worksheet. Repeat locally on side B.

Avoid copying private-key files into temporary folders or passing secrets through shell history. Do not upload a key to an online decoder. If the platform cannot reveal the active public key safely, use its supported enrollment or administration interface and record the public identity it reports.

Confirm active state rather than assuming the file on disk was loaded. A service may still run with an older key after a configuration file changed, or an interface may have been recreated from another source. Compare the live public identity with the intended configuration record without printing the private key.

Stop here if you cannot establish a trusted local public identity for either side. Ask the authorized administrator for a public-key or fingerprint attestation; do not request the private key.

Step 3: Compare the mapping in both directions

Read side A's peer public key for side B and compare it with B's locally observed public identity. Then read side B's peer public key for A and compare it with A's locally observed public identity. These are two separate edges; one can be current while the other is stale.

Comparison	Result	Interpretation
A expects B = B observed	Match	A's remote-identity record is consistent
A expects B ≠ B observed	Mismatch	A's peer record or B's intended identity is stale/wrong
B expects A = A observed	Match	B's remote-identity record is consistent
B expects A ≠ A observed	Mismatch	B's peer record or A's intended identity is stale/wrong
Both edges match	No static public-key mismatch shown	Test PSK, endpoint, path, and peer selection

The mismatch identifies an inconsistent edge, not automatically a guilty person or machine. Verify which public identity is authorized in the enrollment source of truth. A device may have been legitimately rekeyed while the server record missed the update, or an unauthorized local replacement may be the stale side.

Use exact public-key comparison in a protected administrative session when possible. If tickets or spoken verification cannot carry the full public key safely, compare a cryptographic fingerprint calculated with the same documented algorithm and encoding on both ends. Label the algorithm; a shortened visual prefix alone can collide or be transcribed incorrectly.

Step 4: Handle optional preshared keys without revealing them

First determine whether both peer records are intended to use a PSK. “Present” on one side and “absent” on the other is already an inconsistency. If both are present, confirm that they came from the same controlled generation and distribution event.

When policy permits local verification, calculate a keyed or cryptographic fingerprint in place and compare only the resulting controlled identifier through an approved channel. Do not use a fast unsalted hash as a general way to publish a low-entropy secret. The safest operational method is often to redeploy a newly generated PSK to both intended records through the secret-management system, without ever displaying it.

Never put the PSK in a command line that remains in history, a process list, or a support message. A wg status indicating that a preshared key is present does not prove the two secret values match.

Step 5: Exclude look-alike failures before rotating keys

Confirm that the endpoint address and UDP port lead to the intended interface. A perfect key mapping cannot answer traffic sent to an old host. Check narrow firewall and packet counters to determine whether handshake initiations arrive and whether responses leave.

Compare the expected peer with the route and AllowedIPs. The AllowedIPs guide explains how prefixes bind traffic to peers. Wrong prefixes can produce no data after a valid handshake, while duplicate or misplaced peer records can make you inspect the wrong counters.

Check that both sides are using the intended configuration generation and that a restart, container, network namespace, or management agent did not load another file. Do not infer a key mismatch from a generic “no response” error when you cannot observe the far side.

Step 6: Correct only the proven stale edge

Once the enrollment source of truth identifies the authorized public identity, update the inconsistent remote peer record through the supported configuration channel. Do not copy the remote private key as a shortcut. Preserve the old public record and change ticket reference long enough for rollback and audit, subject to local policy.

If the local private key itself was replaced without authorization or its confidentiality is uncertain, treat that as a security event. Generate a new local key pair in the approved environment, distribute only the new public key to every authorized peer, revoke the old identity, and verify that no stale peer remains. This is broader than fixing one typo and may require administrator coordination.

For a PSK inconsistency, deploy one new secret to both sides through the approved secret channel. Avoid temporarily removing the PSK merely to make the tunnel connect unless the owner explicitly accepts that security change and the protocol policy permits it.

Step 7: Verify the repaired identity and data path

Trigger one authorized connection attempt and confirm that the intended peer's latest-handshake time advances on both sides. Record fresh TX/RX deltas around a small numeric probe. A handshake proves the repaired identity mapping; counter movement and the application test prove later stages separately.

Verify that the endpoint, assigned prefixes, and route still correspond to the labeled device. Key repair should not silently authorize broader AllowedIPs or a different client address. Remove temporary diagnostic access and sanitized worksheets according to retention policy.

If the public edges and PSK provenance match but no handshake occurs, stop regenerating keys. Return to endpoint reachability, service state, and firewall evidence. If the handshake works but data does not, follow the counter matrix instead.

When is a managed VPN app simpler than hand-kept keys?

Key mismatches are a maintenance cost of running your own peers. If all you need is a private connection for your own devices, AethoVPN offers a route without that bookkeeping: its documented steps are continuing with an email verification code, installing the client on Windows, Linux, or Android (or running the website setup wizard on Mac and iPhone with a Pro or Premium plan), and choosing a location in the app. Nothing in that setup imports or checks WireGuard keys, so a mismatch between peers you run still has to be fixed by comparing public keys on both ends; and never send private keys or PSKs to any support desk, including AethoVPN's. Create an account with your email to compare the managed route with maintaining keys yourself.

Summary

Label the exact active endpoints and peer records before comparing identities.
Derive or display each public identity locally; never move private keys for diagnosis.
Compare A's expected B key with B's observed public key, then repeat in reverse.
Treat optional PSK state as a separate secret-distribution check.
Exclude endpoint, firewall, process-generation, route, and AllowedIPs look-alikes.
Correct only the proven stale edge and verify handshake and data as separate gates.

FAQ

Can I tell which side is wrong from “no handshake”?

No. Silence is compatible with key mismatch, wrong endpoint, blocked UDP, stopped service, NAT expiry, or an offline peer. You need trusted observations from both sides.

Is a WireGuard public key safe to share?

It is not secret like a private key, but it is still a stable peer identifier. Share it only with the intended administrator and avoid publishing complete topology or endpoint context.

Can I compare private keys directly?

Do not. Each private key must remain on its own authorized endpoint or secret-management system. Derive public keys locally and compare those instead.

Does a current handshake rule out a key mismatch?

It rules out a mismatch for the active static identities and optional PSK used by that peer at that handshake time. It does not prove that another peer record or later data route is correct.

How do I know whether the PSKs match?

Confirm common secret provenance or use an approved in-place fingerprint procedure. A mere “preshared key present” status cannot show equality, and raw PSKs must not be copied into diagnostics.

Should I regenerate both key pairs whenever WireGuard fails?

No. Broad rotation destroys evidence and creates more records to distribute. Rotate only after identifying stale material or when compromise policy requires it.

What should I send to support about a WireGuard key mismatch?

Send sanitized endpoint labels, timestamps, software versions, latest-handshake observations, the two public-key comparisons or approved fingerprints, and the first failed stage. Never send private keys, PSKs, complete profiles, or raw dumps.

Disclaimer: This guide provides general technical troubleshooting information. Handle key material only through authorized systems, and treat suspected private-key exposure as a security event.

Sources:

WireGuard, "Protocol & Cryptography": https://www.wireguard.com/protocol/
WireGuard, "WireGuard: Next Generation Kernel Network Tunnel": https://www.wireguard.com/papers/wireguard.pdf
WireGuard Tools, "wg(8)": https://git.zx2c4.com/wireguard-tools/tree/src/man/wg.8

Sources checked 12 September 2026.

Related Articles:

WireGuard Key Mismatch: How to Identify the Failing Side