apache/maven · error · ToolchainManagerException

Error creating toolchain of type {}

Error message

Error creating toolchain of type {}

What it means

DefaultToolchainManager looks up a ToolchainFactory by the <type> declared in each toolchains.xml entry and delegates creation. If that factory throws ToolchainFactoryException (invalid toolchain definition), the manager wraps it as ToolchainManagerException naming the type. A missing factory for a type is only logged as an error, not thrown, so this exception always means a factory rejected the entry.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultToolchainManager.java:108

        Map<String, Object> context = retrieveContext(session);
        ToolchainModel model = (ToolchainModel) context.get("toolchain-" + type);
        return Optional.ofNullable(model).flatMap(this::createToolchain);
    }

    @Override
    public void storeToolchainToBuildContext(@Nonnull Session session, @Nonnull Toolchain toolchain) {
        Map<String, Object> context = retrieveContext(session);
        context.put("toolchain-" + toolchain.getType(), toolchain.getModel());
    }

    private Optional<Toolchain> createToolchain(ToolchainModel model) {
        String type = Objects.requireNonNull(model.getType(), "model.getType()");
        ToolchainFactory factory = factories.get(type);
        if (factory != null) {
            try {
                return Optional.of(factory.createToolchain(model));
            } catch (ToolchainFactoryException e) {
                throw new ToolchainManagerException("Error creating toolchain of type " + type, e);
            }
        } else {
            logger.error("Missing toolchain factory for type: " + type + ". Possibly caused by misconfigured project.");
        }
        return Optional.empty();
    }

    private static final SessionData.Key<ConcurrentHashMap<Project, ConcurrentHashMap<String, Object>>>
            TOOLCHAIN_CONTEXT_KEY = (SessionData.Key) SessionData.key(ConcurrentHashMap.class, "toolchain-context");

    protected Map<String, Object> retrieveContext(Session session) {
        Optional<Project> current = session.getService(Lookup.class).lookupOptional(Project.class);
        if (current.isPresent()) {
            var map = session.getData().computeIfAbsent(TOOLCHAIN_CONTEXT_KEY, ConcurrentHashMap::new);
            return map.computeIfAbsent(current.get(), p -> new ConcurrentHashMap<>());
        }
        return new HashMap<>();
    }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Read the cause - the ToolchainFactoryException carries the specific reason
2. Fix the toolchains.xml entry for the named type: paths must exist and required properties must be set
3. Comment out toolchain entries one by one to isolate which entry fails
4. For custom providers, run their validation directly on the model during development

Example fix

<!-- before -->
<toolchain>
  <type>jdk</type>
  <provides><version>17</version></provides>
  <configuration>
    <jdkHome>/opt/jdks/17</jdkHome> <!-- path missing on this machine -->
  </configuration>
</toolchain>

<!-- after -->
<toolchain>
  <type>jdk</type>
  <provides><version>17</version></provides>
  <configuration>
    <jdkHome>/opt/jdk-17.0.9</jdkHome> <!-- existing path -->
  </configuration>
</toolchain>

try {
    Optional<Toolchain> tc = toolchainManager.getToolchainFromBuildContext("jdk", session);
} catch (ToolchainManagerException e) {
    String type = /* from message */ e.getMessage();
    log.error("toolchain of type failed: {}", e.getMessage(), e.getCause());
    // fix the toolchains.xml entry named in the cause
}

When it happens

Trigger: A toolchains.xml entry whose type maps to a factory that fails: jdk toolchain with a missing or invalid home, or a custom toolchain provider validating properties and throwing ToolchainFactoryException.

Common situations: CI images where paths in toolchains.xml do not exist; typos or omissions in required toolchain properties; custom toolchain providers with stricter validation than Maven's built-ins.

Related errors

• Only fully-qualified sets allowed in multiple set scenario:
• Single version must be surrounded by []: {}
• Cannot read toolchains file at " + userToolchainsFile.getAbs
• Provides token '" + key + "' doesn't have any value configur
• Java toolchain without the jdkHome configuration element.

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/6018455aef2a1a50. Report an issue: GitHub.