spring-projects/spring-security · error · Saml2Exception

Unsupported element of type

Error message

Unsupported element of type

What it means

During metadata deserialization, OpenSAML's UnmarshallerFactory returns no Unmarshaller for the document's root element, meaning the XML namespace/element is not a recognized OpenSAML type. Spring Security surfaces this as a Saml2Exception including the element's tag name.

Source

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

	private interface OpenSamlDeserializer {

		XMLObject deserialize(InputStream serialized);

	}

	private static class OpenSaml5Deserializer implements OpenSamlDeserializer {

		@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. Fetch the URL manually and check the root element; point fromMetadataLocation at the true metadata document
  2. Ensure the server returns the metadata XML directly (no HTML login redirect) and with correct Content-Type
  3. If a proxy is interfering, bypass it or provide the metadata as a local file/classpath resource instead
  4. If OpenSAML registry initialization is the issue, ensure the OpenSAMLInitializationService/standard providers are on the classpath

Example fix

// before: URL that redirects to HTML login
.fromMetadataLocation("https://idp.example.com/protected-metadata")
// after: use a direct or authenticated-fetch source
.fromMetadataLocation("classpath:idp-metadata.xml")
Defensive patterns

Strategy: validation

Validate before calling

byte[] body = fetch(metadataUrl);
Document doc = parseXml(body);
String rootNs = doc.getDocumentElement().getNamespaceURI();
if (!"urn:oasis:names:tc:SAML:2.0:metadata".equals(rootNs)) {
    throw new IllegalArgumentException("Root element is not SAML 2.0 metadata: " + rootNs);
}

Try / catch

try {
    return RelyingPartyRegistrations.fromMetadata(in);
} catch (Saml2Exception ex) {
    if (ex.getMessage() != null && ex.getMessage().startsWith("Unsupported element of type")) {
        // includes offending tag name — route to correct metadata endpoint
        throw new IllegalStateException("Unknown root element served at metadata URL", ex);
    }
    throw ex;
}

Prevention

When it happens

Trigger: RelyingPartyRegistrations.fromMetadataLocation/fromMetadata handed an InputStream whose root element is not a SAML-metadata element (e.g. <html>, <Error>, <soap:Envelope>), so factory.getUnmarshaller(element) returns null.

Common situations: Metadata URL redirects to a login page (HTML root); proxy/firewall returns an error XML; wrong content served with a 200 status; OpenSAML registry not initialized so even valid elements have no unmarshaller (rare).

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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