mybatis/mybatis-3 · error · BuilderException

No environment specified.

Error message

No environment specified.

What it means

Thrown by XMLConfigBuilder.isSpecifiedEnvironment() while parsing <environments> in mybatis-config.xml. The field 'environment' holds the value of the default attribute of the <environments> element; when it is null the builder cannot decide which environment applies, so it refuses to continue. Every <environment id="..."> child is validated against that default.

Source

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

          try (InputStream inputStream = Resources.getUrlAsStream(url)) {
            XMLMapperBuilder mapperParser = new XMLMapperBuilder(inputStream, configuration, url,
                configuration.getSqlFragments());
            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 default="<envId>" to the <environments> element matching the id of one child <environment id="...">
2. If you build Configuration programmatically, call config.setEnvironment(...) instead of relying on XML
3. Check for stray whitespace/empty value in the default attribute

Example fix

<!-- before -->
<environments>
  <environment id="development">...</environment>
</environments>

<!-- after -->
<environments default="development">
  <environment id="development">...</environment>
</environments>

String def = environmentsElement.getAttribute("default");
if (def == null || def.isEmpty()) throw new IllegalStateException("<environments> requires default=...");
boolean matches = Stream.of(environmentChildren).anyMatch(c -> def.equals(c.getAttribute("id")));
if (!matches) throw new IllegalStateException("default environment '" + def + "' has no matching <environment id>");

When it happens

Trigger: <environments> element present with <environment> children but the default attribute is missing, e.g. <environments>...</environments> with no default="development"; also when the default attribute value is empty. Thrown during SqlSessionFactoryBuilder.build().

Common situations: Hand-editing mybatis-config.xml and dropping the default attribute; merging config files during refactoring; tutorials that show only one environment and omit default, which fails on strict versions.

Related errors

• Environment requires an id attribute.
• 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/002c76be6862b920. Report an issue: GitHub.