spring-projects/spring-security · error · Saml2Exception

Unable to resolve Builder for

Error message

Unable to resolve Builder for 

What it means

OpenSaml5Template.build(QName) looks up an XMLObjectBuilder from the OpenSAML global builder registry for the requested element name. If no builder is registered for that QName, it throws Saml2Exception('Unable to resolve Builder for ...'). This means OpenSAML's ObjectProvider registry lacks a builder for the requested SAML element.

Source

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

import org.springframework.security.saml2.core.Saml2ParameterNames;
import org.springframework.security.saml2.core.Saml2X509Credential;
import org.springframework.util.Assert;
import org.springframework.web.util.UriComponentsBuilder;
import org.springframework.web.util.UriUtils;

/**
 * For internal use only. Subject to breaking changes at any time.
 */
@NullMarked
final class OpenSaml5Template implements OpenSamlOperations {

	private static final Log logger = LogFactory.getLog(OpenSaml5Template.class);

	@Override
	public <T extends XMLObject> T build(QName elementName) {
		XMLObjectBuilder<?> builder = XMLObjectProviderRegistrySupport.getBuilderFactory().getBuilder(elementName);
		if (builder == null) {
			throw new Saml2Exception("Unable to resolve Builder for " + elementName);
		}
		return (T) builder.buildObject(elementName);
	}

	@Override
	public <T extends XMLObject> T deserialize(String serialized) {
		return deserialize(new ByteArrayInputStream(serialized.getBytes(StandardCharsets.UTF_8)));
	}

	@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);

View on GitHub (pinned to 96852e8860)

Solutions

1. Use a QName that matches a standard SAML element (correct namespace URI, e.g. SAML 2.0 assertion namespace)
2. Ensure OpenSAML initialization ran (Spring's OpenSamlInitializationService / OpenSaml4/5 library defaults)
3. Register a custom builder via XMLObjectProviderRegistrySupport.registerObjectProvider for extension elements
4. Log the element QName and compare against registered providers

Example fix

// before
QName qname = new QName("urn:wrong:ns", "Response");
template.build(qname); // no builder for this QName
// after
QName qname = new QName(SAMLConstants.SAML20_NS, "Response", SAMLConstants.SAML20_PREFIX);
template.build(qname);

XMLObjectBuilder<?> builder = XMLObjectProviderRegistrySupport.getBuilderFactory().getBuilder(elementName);
if (builder == null) {
    throw new IllegalArgumentException("No OpenSAML builder registered for " + elementName);
}

try {
    XMLObject obj = template.build(elementName);
} catch (Saml2Exception ex) {
    throw new IllegalStateException("Builder missing for " + elementName + " — register an ObjectProvider or check the QName", ex);
}

When it happens

Trigger: Calling OpenSamlTemplate.build(elementName) with a QName for which XMLObjectProviderRegistrySupport.getBuilderFactory().getBuilder(qname) returns null — e.g. a custom or non-standard element, or OpenSAML's default providers were never initialized (initialize()/XMLObjectProviderRegistry not bootstrapped).

Common situations: Using a misspelled or namespaced QName; requesting vendor extension elements without registering custom builders; calling build() very early before OpenSaml5's static initialization registered defaults.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Unsupported element of type
• Saml2Exception wrapping MarshallingException during serializ
• Saml2Exception wrapping exception while signing XMLObject
• Cannot apply {configurer} to already built object
• This object has already been built

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