mybatis/mybatis-3 · error · BuilderException

Error occurred when getting DB product name.

Error message

Error occurred when getting DB product name.

What it means

VendorDatabaseIdProvider wraps any SQLException raised while fetching the database product name into a BuilderException. Resolving databaseId requires a live connection (Connection.getMetaData().getDatabaseProductName()), so connection failures surface here during startup.

Source

Thrown at src/main/java/org/apache/ibatis/mapping/VendorDatabaseIdProvider.java:47

 * It returns database product name as a databaseId. If the user provides a properties it uses it to translate database
 * product name key="Microsoft SQL Server", value="ms" will return "ms". It can return null, if no database product name
 * or a properties was specified and no translation was found.
 *
 * @author Eduardo Macarron
 */
public class VendorDatabaseIdProvider implements DatabaseIdProvider {

  private Properties properties;

  @Override
  public String getDatabaseId(DataSource dataSource) {
    if (dataSource == null) {
      throw new NullPointerException("dataSource cannot be null");
    }
    try {
      return getDatabaseName(dataSource);
    } catch (SQLException e) {
      throw new BuilderException("Error occurred when getting DB product name.", e);
    }
  }

  @Override
  public void setProperties(Properties p) {
    this.properties = p;
  }

  private String getDatabaseName(DataSource dataSource) throws SQLException {
    String productName = getDatabaseProductName(dataSource);
    if (properties == null || properties.isEmpty()) {
      return productName;
    }
    return properties.entrySet().stream().filter(entry -> productName.contains((String) entry.getKey()))
        .map(entry -> (String) entry.getValue()).findFirst().orElse(null);
  }

  private String getDatabaseProductName(DataSource dataSource) throws SQLException {

View on GitHub (pinned to 008069adb1)

Solutions

1. Verify the DataSource can open a connection with the same settings outside MyBatis (e.g. a plain JDBC snippet).
2. Check the JDBC URL, driver class, and credentials in the environment block.
3. Fix network/firewall access to the database host and port.
4. Temporarily remove the <databaseIdProvider> element to confirm it is the failing component.

try (Connection c = dataSource.getConnection()) {
  c.getMetaData().getDatabaseProductName(); // proves connectivity before MyBatis startup
}

try {
  sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);
} catch (BuilderException e) {
  if (e.getMessage().contains("DB product name")) {
    // surface as environment/config problem: check URL, driver, credentials
  }
  throw e;
}

When it happens

Trigger: A databaseIdProvider is configured and MyBatis opens a connection to identify the DB, but the JDBC URL, driver, credentials, or network are wrong; the pool rejects the connection.

Common situations: Bad JDBC URL or missing driver on classpath; DB unreachable from the build/deploy environment; credentials changed; connection pool max-size exhausted at startup.

Related errors

• Error parsing Mapper XML. The XML location is '{resource}'.
• Error accessing PooledConnection. Connection is invalid.
• Unknown DataSource property: ${propertyName}
• Error getting constructor collection nested result map value
• Error getting nested result map values for '{}'. Cause: {}

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