What causes "Failed to deserialize payload" in spring-projects/spring-security?

Inspect the wrapped cause (ex.getCause()) to find the underlying parser/unmarshaller error.

spring-projects/spring-security · error · Saml2Exception

Failed to deserialize payload

Error message

Failed to deserialize payload

What it means

This is the catch-all in OpenSaml5Template.deserialize(): any non-Saml2Exception failure while parsing/unmarshalling the payload (ParserPool parse errors, SAX/IO problems, unmarshalling failures) is wrapped in a Saml2Exception with the original as cause. It signals the serialized XML could not be turned into an OpenSAML object.

Source

Thrown at saml2/saml2-service-provider/src/opensaml5Main/java/org/springframework/security/saml2/provider/service/web/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

Inspect the wrapped cause (ex.getCause()) to find the underlying parser/unmarshaller error.
Verify the input string is plain XML, not Base64- or URL-encoded, before calling deserialize().
Validate the XML well-formedness with a standalone parser to isolate the malformed portion.
Confirm the SAML message was not truncated or modified in transit (check relay/proxy handling and request parameter decoding, e.g. use URLDecoder and the correct charset).

Example fix

// before
String encoded = request.getParameter("SAMLResponse");
Response r = template.deserialize(encoded); // still base64

// after
String decoded = new String(Base64.getMimeDecoder().decode(request.getParameter("SAMLResponse")), StandardCharsets.UTF_8);
Response r = template.deserialize(decoded);

Defensive patterns

Strategy: try-catch

Validate before calling

try { DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new InputSource(new StringReader(serialized))); } catch (Exception e) { throw new IllegalArgumentException("Malformed XML payload", e); }

Try / catch

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

Prevention

Always inspect ex.getCause() for the underlying parser error
Ensure proper Base64/URL decoding with correct charset before deserialize()
Log a sanitized snippet of the payload to catch truncation/encoding issues

When it happens

Trigger: Calling OpenSaml5Template.deserialize(String) where pool.parse(serialized) or unmarshaller.unmarshall(element) throws any Exception other than Saml2Exception (malformed XML, encoding issues, schema violations during unmarshalling, IO errors).

Common situations: Passing URL-encoded or Base64 data that was not first decoded; XML with invalid characters or mismatched tags; payloads altered in transit (whitespace/signature wrapping breaking parsing); wrong charset causing parse failures.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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