mybatis/mybatis-3 · error · BuilderException

Environment requires an id attribute.

Error message

Environment requires an id attribute.

What it means

Thrown by XMLConfigBuilder.isSpecifiedEnvironment() when an <environment> child element inside <environments> lacks the id attribute. Environments are identified purely by id (e.g. 'development', 'production'), and the builder needs it to match against the default environment, so a missing id is fatal during config parsing.

Source

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

            mapperParser.parse();
          }
        } else if (resource == null && url == null && mapperClass != null) {
          Class<?> mapperInterface = Resources.classForName(mapperClass);
          configuration.addMapper(mapperInterface);
        } else {
          throw new BuilderException(
              "A mapper element may only specify a url, resource or class, but not more than one.");
        }
      }
    }
  }

  private boolean isSpecifiedEnvironment(String id) {
    if (environment == null) {
      throw new BuilderException("No environment specified.");
    }
    if (id == null) {
      throw new BuilderException("Environment requires an id attribute.");
    }
    return environment.equals(id);
  }

  private static Configuration newConfig(Class<? extends Configuration> configClass) {
    try {
      return configClass.getDeclaredConstructor().newInstance();
    } catch (Exception ex) {
      throw new BuilderException("Failed to create a new Configuration instance.", ex);
    }
  }

}

View on GitHub (pinned to 008069adb1)

Solutions

1. Add a unique id attribute to every <environment> element
2. Ensure the id matches the default attribute of <environments> for at least one environment
3. Enable XSD validation in your IDE against mybatis-3-config.xsd to catch this at edit time

Example fix

<!-- before -->
<environment>
  <transactionManager type="JDBC"/>
</environment>

<!-- after -->
<environment id="development">
  <transactionManager type="JDBC"/>
</environment>

for (Element env : environmentChildren) {
  if (env.getAttribute("id") == null || env.getAttribute("id").isEmpty())
    throw new IllegalStateException("<environment> missing required id attribute");
}

When it happens

Trigger: An <environment> element with transactionManager/dataSource children but no id attribute, e.g. <environment> instead of <environment id="development">. Raised while SqlSessionFactoryBuilder.build() walks the environments section.

Common situations: Copying an <environment> block to create a second environment and forgetting to add the new id; XML schema validation disabled so the missing required attribute is not caught earlier; refactoring that strips attributes.

Related errors

• No environment specified.
• There is no 'privateLookupIn(Class, Lookup)' method in java.
• A mapper element may only specify a url, resource or class,
• Unknown execution method for: {name}
• Mapper method '{name}' attempted to return null from a metho

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