mybatis/mybatis-3 · error · BuilderException

The mapper element requires a namespace attribute to be spec

Error message

The mapper element requires a namespace attribute to be specified.

What it means

MapperBuilderAssistant.setCurrentNamespace(null) is called when an XML mapper element carries no namespace attribute. Since every statement id is namespaced as 'namespace.id', a mapper without a namespace cannot be bound, so parsing aborts with this BuilderException.

Source

Thrown at src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java:77

  private String currentNamespace;
  private final String resource;
  private Cache currentCache;
  private boolean unresolvedCacheRef; // issue #676

  public MapperBuilderAssistant(Configuration configuration, String resource) {
    super(configuration);
    ErrorContext.instance().resource(resource);
    this.resource = resource;
  }

  public String getCurrentNamespace() {
    return currentNamespace;
  }

  public void setCurrentNamespace(String currentNamespace) {
    if (currentNamespace == null) {
      throw new BuilderException("The mapper element requires a namespace attribute to be specified.");
    }

    if (this.currentNamespace != null && !this.currentNamespace.equals(currentNamespace)) {
      throw new BuilderException(
          "Wrong namespace. Expected '" + this.currentNamespace + "' but found '" + currentNamespace + "'.");
    }

    this.currentNamespace = currentNamespace;
  }

  public String applyCurrentNamespace(String base, boolean isReference) {
    if (base == null) {
      return null;
    }
    if (isReference) {
      // is it qualified with any namespace yet?
      if (base.contains(".")) {
        return base;

View on GitHub (pinned to 008069adb1)

Solutions

1. Add namespace="fully.qualified.MapperInterface" to the root <mapper> element
2. If the file is generated, fix the template so the namespace placeholder is populated

Example fix

<!-- before -->
<mapper>
  <select id="find" ...>
<!-- after -->
<mapper namespace="com.example.UserMapper">
  <select id="find" ...>

// in build/CI: parse each mapper XML and assert the root attribute
// Document d = parse(file); d.getDocumentElement().getAttribute("namespace").isBlank() -> fail

When it happens

Trigger: A mapper XML file whose root element is <mapper> without the namespace attribute; dynamically generated mapper XML omitting the attribute; DTD-valid file but namespace lost during templating/merge.

Common situations: Hand-writing a new mapper file from a template that lacks the attribute; code-generation templates with an unfilled ${namespace} placeholder; refactoring that accidentally deletes the attribute.

Related errors

• Wrong namespace. Expected '{currentNamespace}' but found '{c
• Error resolving JdbcType. Cause: {cause}
• Error resolving ResultSetType. Cause: {cause}
• Error resolving ParameterMode. Cause: {cause}
• Error creating instance. Cause: {cause}

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