mybatis/mybatis-3 · error · BuilderException

Each XMLConfigBuilder can only be used once.

Error message

Each XMLConfigBuilder can only be used once.

What it means

Error "Each XMLConfigBuilder can only be used once." thrown in mybatis/mybatis-3.

Source

Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:107

  public XMLConfigBuilder(Class<? extends Configuration> configClass, InputStream inputStream, String environment,
      Properties props) {
    this(configClass, new XPathParser(inputStream, true, props, new XMLMapperEntityResolver()), environment, props);
  }

  private XMLConfigBuilder(Class<? extends Configuration> configClass, XPathParser parser, String environment,
      Properties props) {
    super(newConfig(configClass));
    ErrorContext.instance().resource("SQL Mapper Configuration");
    this.configuration.setVariables(props);
    this.parsed = false;
    this.environment = environment;
    this.parser = parser;
  }

  public Configuration parse() {
    if (parsed) {
      throw new BuilderException("Each XMLConfigBuilder can only be used once.");
    }
    parsed = true;
    parseConfiguration(parser.evalNode("/configuration"));
    return configuration;
  }

  private void parseConfiguration(XNode root) {
    try {
      // issue #117 read properties first
      propertiesElement(root.evalNode("properties"));
      Properties settings = settingsAsProperties(root.evalNode("settings"));
      loadCustomVfsImpl(settings);
      loadCustomLogImpl(settings);
      typeAliasesElement(root.evalNode("typeAliases"));
      pluginsElement(root.evalNode("plugins"));
      objectFactoryElement(root.evalNode("objectFactory"));
      objectWrapperFactoryElement(root.evalNode("objectWrapperFactory"));
      reflectorFactoryElement(root.evalNode("reflectorFactory"));

View on GitHub (pinned to 008069adb1)

Solutions

1. Create a new XMLConfigBuilder instance for each configuration parse instead of reusing one.
2. Do not call parse() twice on the same builder; rebuild it from the reader/resource.

When it happens

Trigger: Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:107 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/5bdb6fa417a30fe4. Report an issue: GitHub.