{"record":{"id":"46e8dac01d351f11","repo":"Netflix/zuul","slug":"unknown-psk-identity","errorCode":"unknown_psk_identity","errorMessage":"Unknown or null client PSk identity","messagePattern":"Unknown or null client PSk identity","errorType":"error_code","errorClass":"TlsFatalAlert","httpStatus":null,"severity":"error","filePath":"zuul-core/src/main/java/com/netflix/zuul/netty/server/psk/ZuulPskServer.java","lineNumber":170,"sourceCode":"     * SneakyThrows allows up to compile and it will throw the exception at runtime.\n     */\n    @Override\n    @SneakyThrows\n    public TlsPSKExternal getExternalPSK(Vector clientPskIdentities) {\n        byte[] clientPskIdentity = ((PskIdentity) clientPskIdentities.get(0)).getIdentity();\n        byte[] psk;\n        try {\n            this.ctx\n                    .channel()\n                    .attr(TlsPskHandler.CLIENT_PSK_IDENTITY_ATTRIBUTE_KEY)\n                    .set(new ClientPSKIdentityInfo(List.copyOf(Bytes.asList(clientPskIdentity))));\n            psk = externalTlsPskProvider.provide(\n                    clientPskIdentity,\n                    this.context.getSecurityParametersHandshake().getClientRandom());\n        } catch (PskCreationFailureException e) {\n            throw switch (e.getTlsAlertMessage()) {\n                case unknown_psk_identity ->\n                    new TlsFatalAlert(AlertDescription.unknown_psk_identity, \"Unknown or null client PSk identity\");\n                case decrypt_error ->\n                    new TlsFatalAlert(AlertDescription.decrypt_error, \"Invalid or expired client PSk identity\");\n            };\n        }\n        TlsSecret pskTlsSecret = getCrypto().createSecret(psk);\n        int prfAlgorithm = getPRFAlgorithm13(getSelectedCipherSuite());\n        return new BasicTlsPSKExternal(clientPskIdentity, pskTlsSecret, prfAlgorithm);\n    }\n\n    @Override\n    public void notifyAlertRaised(short alertLevel, short alertDescription, String message, Throwable cause) {\n        super.notifyAlertRaised(alertLevel, alertDescription, message, cause);\n        Consumer<String> loggerFunc = (alertLevel == AlertLevel.fatal) ? LOGGER::error : LOGGER::debug;\n        loggerFunc.accept(\"TLS/PSK server raised alert: \" + AlertLevel.getText(alertLevel) + \", \"\n                + AlertDescription.getText(alertDescription));\n        if (message != null) {\n            loggerFunc.accept(\"> \" + message);\n        }","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/Netflix/zuul/blob/14bf53c52dcf571894619ff65a674cbe2cce3ac6/zuul-core/src/main/java/com/netflix/zuul/netty/server/psk/ZuulPskServer.java#L152-L188","documentation":"In ZuulPskServer.getExternalPSK, when the external TLS-PSK provider throws PskCreationFailureException with the TLS alert unknown_psk_identity, it is translated into a TlsFatalAlert(unknown_psk_identity, 'Unknown or null client PSk identity'). This means the PSK identity sent by the client in the TLS handshake does not match any identity known to the configured externalTlsPskProvider (or was null), so the TLS 1.3 handshake is aborted.","triggerScenarios":"Thrown at zuul-core/src/main/java/com/netflix/zuul/netty/server/psk/ZuulPskServer.java:170 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Ensure the client is configured with a PSK identity that the externalTlsPskProvider actually knows","Check that the provider's key/identity store is loaded and in sync with what clients use","Rotate or distribute PSKs consistently between client and server","Log the received identity (as done via CLIENT_PSK_IDENTITY_ATTRIBUTE_KEY) to diagnose mismatched or empty identities"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"14bf53c52dcf571894619ff65a674cbe2cce3ac6","analyzedAt":"2026-09-07T10:00:54.873Z","contentChangedAt":"2026-09-07T10:00:54.873Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}