Keystore error on Android VPN: re-enroll, unlock or retry?

The profile is still listed, the certificate still shows as installed, and the connect button fails with a message that says Keystore error and nothing else. Before you clear app storage or hand the phone in, establish which key operation failed. Three outcomes produce that same dialog, and they respond to three different actions — only one of which is destructive. The comparison is worth ten minutes because the wrong branch costs you the identity you were trying to keep.

Three failures behind one dialog

The first is authentication. The key exists and is valid, but using it requires the user to prove presence — a device unlock, a biometric, or a work-profile challenge. If the lock timeout, the enrolled biometrics or the profile state changed recently, key use can fail while the key itself is perfectly fine.

The second is permanent invalidation. Some key material is invalidated by platform policy when the lock method is reset or biometric enrollment changes, because the binding that protected it no longer holds. The key cannot be repaired and retrying it is not a recovery plan; the identity must be replaced through the enrollment process that issued it.

The third is a provider failure: the keystore service could not complete the operation right now. This is the class that is sometimes worth retrying, and the only one.

Notice that two of the three are non-destructive and one has no fix at all at the device level. None of them is addressed by wiping the phone, which is the step people take first because the dialog gives them nothing else to act on.

Re-enrollment versus a data clear

These two look similar from the outside and are not. Re-enrollment asks the issuing system for a new identity — a fresh certificate or key bound to this device — and retires the old one. A data clear deletes the app's stored state, which may remove the reference to the key without removing the key, or may remove the key and leave you with no authority to recreate it.

The distinction matters because non-exportable keys are, by design, not portable. They live in the device's keystore backed by whatever hardware or provider is available, and they are not something a backup captures and a restore reinstates. If the deployment's identity is a non-exportable key, plan on re-enrollment as the recovery, and confirm in advance that you have an approved route to obtain that enrollment — some organizations require private network access for it, which is exactly what the broken VPN was providing.

So the ordering is: try the supported authentication path, then determine whether the key is permanently invalid, and only replace the identity if it is. Clearing storage belongs last, after you know what will be recreated, not first because it is easy.

Retry only what is retryable

Older platform versions collapsed keystore errors into a single exception, which is why so many clients retry everything. From API 33 the exception type carries structure: a numeric error, a transient-failure flag, and a retry policy. For a client developer, the retry policy is meaningful only when the transient flag is true; a permanent invalidation has no retry schedule, and hammering it in a loop simply drains the battery and fills the log.

If you are diagnosing rather than writing the client, the practical consequence is the same. Identical failures on every attempt rule out a one-off glitch, but they do not separate a permanently invalidated key from a provider that has been unavailable for a while — a provider outage looks exactly the same on the tenth retry as on the first. Without the API 33 structured fields, treat repetition as a reason to look for a second signal — the error code if your build exposes one, the operator’s status, or a different key on the same device succeeding — rather than as evidence that the key is dead.

Read the cause chain, not the label

Applications wrap the original exception, and the friendly string in the UI frequently hides the one field that decides the branch. Preserve the cause chain and the timestamp of the attempt: the outer exception usually names the operation, and the cause names the key condition.

Resist the inference that two failing apps prove a defective handset. Different keys can be backed by different providers and security levels, and an app that still works may not exercise the same operation at all — a signature, a decryption and a key attestation are different requests to the same service. The KeyStoreException reference describes the structured fields on newer API levels and is the place to check what your build can actually report.

What would support a hardware conclusion is narrower than most people assume: the same operation, on the same provider, failing across independent keys with a provider-level error rather than a key-level one. That is a question for the platform's diagnostics, not for a support forum thread about a batch of devices.

What to record while you decide

Capture the Android build, the client version, the selected profile, the operation that failed, and whether anything changed recently — an OS update, a lock-screen change, a new fingerprint, a re-enrollment. Record the sequence as context rather than as proof of cause; a lock change before a key failure is a plausible correlation, not a demonstration.

Then act on the branch you established. Transient: keep the identity, use the supported retry path. Authentication required: complete the supported unlock flow and keep the lock policy the deployment requires rather than disabling it to get past a dialog. Permanently invalid: replace and retire the identity through normal enrollment.

Finish by proving the outcome on a fresh authorized connection, to a real resource, with server validation still enabled. Anything that only works with certificate checks relaxed has not fixed the key problem — it has moved it into the network layer, where it will surface later with worse symptoms.

• Three branches: needs authentication, permanently invalid, provider-transient.
• Only the third one benefits from retrying, and only per its retry policy.
• Replacement enrollment restores access; a data clear removes the option.
• Verify with a fresh connection and normal server identity checks.