spring-projects/spring-security · error · Saml2Exception

Failed to deserialize payload

Error message

Failed to deserialize payload

What it means

OpenSaml5Template.deserialize (authentication package) catches any exception other than Saml2Exception during parsing or unmarshalling — SAX parse errors, IOException, runtime failures — and rethrows as Saml2Exception('Failed to deserialize payload') with the original exception attached as the cause.

Source

Thrown at saml2/saml2-service-provider/src/opensaml5Main/java/org/springframework/security/saml2/provider/service/authentication/OpenSaml5Template.java:160

	@Override
	public <T extends XMLObject> T deserialize(InputStream serialized) {
		try {
			ParserPool pool = XMLObjectProviderRegistrySupport.getParserPool();
			Assert.notNull(pool, "ParserPool must be configured");
			Document document = pool.parse(serialized);
			Element element = document.getDocumentElement();
			UnmarshallerFactory factory = XMLObjectProviderRegistrySupport.getUnmarshallerFactory();
			Unmarshaller unmarshaller = factory.getUnmarshaller(element);
			if (unmarshaller == null) {
				throw new Saml2Exception("Unsupported element of type " + element.getTagName());
			}
			return (T) unmarshaller.unmarshall(element);
		}
		catch (Saml2Exception ex) {
			throw ex;
		}
		catch (Exception ex) {
			throw new Saml2Exception("Failed to deserialize payload", ex);
		}
	}

	@Override
	public OpenSaml5SerializationConfigurer serialize(XMLObject object) {
		Marshaller marshaller = XMLObjectProviderRegistrySupport.getMarshallerFactory().getMarshaller(object);
		Assert.notNull(marshaller, "Marshaller for " + object.getElementQName() + " must be configured");
		try {
			return serialize(marshaller.marshall(object));
		}
		catch (MarshallingException ex) {
			throw new Saml2Exception(ex);
		}
	}

	@Override
	public OpenSaml5SerializationConfigurer serialize(Element element) {
		return new OpenSaml5SerializationConfigurer(element);

View on GitHub (pinned to 96852e8860)

Solutions

1. Inspect the cause of the Saml2Exception — it pinpoints the underlying parse failure (line/column or exception type).
2. Confirm the SAML message is base64-decoded and URL-decoded exactly once, with correct charset (UTF-8).
3. Log the raw payload before deserialization and validate it is well-formed XML from the expected sender.
4. Check for intermediary proxies or logging filters that truncate or modify the SAML parameter.

Example fix

// before
String xml = new String(payload); // platform default charset, possibly wrong
// after
String xml = new String(payload, StandardCharsets.UTF_8);

try {
    SAXParserFactory f = SAXParserFactory.newInstance();
    f.setNamespaceAware(true);
    f.newSAXParser().parse(new InputSource(new StringReader(serialized)), new DefaultHandler());
} catch (Exception wellFormedness) {
    throw new IllegalArgumentException("Payload is not well-formed XML", wellFormedness);
}

try {
    return template.deserialize(serialized);
} catch (Saml2Exception ex) {
    log.error("Payload deserialization failed; cause=", ex.getCause());
    throw new Saml2ErrorStatusException(HttpStatus.BAD_REQUEST, ex.getCause());
}

When it happens

Trigger: deserialize(String/InputStream) given malformed, truncated, wrongly encoded, or unparseable XML, or XML that parses but fails inside unmarshall for any non-Saml2Exception reason.

Common situations: SAML message corrupted by incorrect base64/URL decoding; XML containing invalid characters or DTD content rejected by the parser; payloads captured from logs with truncation or HTML error pages; charset mismatches when converting bytes to String.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Failed to deserialize payload
• Failed to deserialize payload
• Unsupported element of type
• Failed to deserialize payload
• Failed to deserialize payload

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/dc9a0918559faf4e. Report an issue: GitHub.