spring-projects/spring-security · error · Saml2Exception

Failed to deserialize payload

Error message

Failed to deserialize payload

What it means

This catch-all wraps any non-Saml2Exception thrown while deserializing the metadata payload (XML parse errors, IO failures, unmarshalling problems) into a Saml2Exception with the message 'Failed to deserialize payload' and the original as cause. It means the metadata bytes could not be turned into an OpenSAML XMLObject.

Source

Thrown at saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/registration/OpenSamlMetadataUtils.java:91

		@Override
		public XMLObject deserialize(InputStream serialized) {
			try {
				ParserPool parserPool = XMLObjectProviderRegistrySupport.getParserPool();
				Assert.notNull(parserPool, "A ParserPool must be configured");
				Document document = parserPool.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 unmarshaller.unmarshall(element);
			}
			catch (Saml2Exception ex) {
				throw ex;
			}
			catch (Exception ex) {
				throw new Saml2Exception("Failed to deserialize payload", ex);
			}
		}

	}

}

View on GitHub (pinned to 96852e8860)

Solutions

1. Validate the metadata XML with a parser (xmllint) to find syntax/encoding errors
2. Re-download the metadata in full and compare sizes/checksums to rule out truncation
3. Ensure the InputStream is fresh and positioned at 0 when passed to fromMetadata
4. Check the cause chain (Saml2Exception#getCause) for the concrete parser error and fix it

Example fix

// before: reusing a consumed stream
InputStream in = metadataStream();
validate(in); fromMetadata(in); // stream exhausted
// after: re-open or buffer first
byte[] bytes = metadataStream().readAllBytes();
validate(new ByteArrayInputStream(bytes));
RelyingPartyRegistration r = RelyingPartyRegistrations.fromMetadata(new ByteArrayInputStream(bytes));

// Well-formedness pre-check before handing stream to the library
DocumentBuilder db = DocumentBuilderFactory.newInstance().newDocumentBuilder();
db.parse(new ByteArrayInputStream(metadataBytes)); // throws SAXException on bad XML

try {
    return RelyingPartyRegistrations.fromMetadata(in);
} catch (Saml2Exception ex) {
    throw new IllegalStateException("Metadata could not be parsed: " + ex.getCause(), ex);
}

When it happens

Trigger: Calling RelyingPartyRegistrations.fromMetadata/collectionFromMetadata with a stream containing malformed XML (syntax errors, encoding mismatch, truncated document) — any Exception other than CertificateException-shaped Saml2Exceptions from the inner path.

Common situations: Metadata file truncated by a partial download; BOM/encoding issues (declared UTF-8 but file is UTF-16); XML not well-formed after manual edits; InputStream already consumed by a previous read.

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

• Unsupported element of type
• Cannot encode certificate
• Metadata response is missing verification certificates, nece
• Metadata response is missing a SingleSignOnService, necessar
• Unsupported element type:

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