mybatis/mybatis-3 · error · IllegalArgumentException

Parameter 'dataSource' must not be null

Error message

Parameter 'dataSource' must not be null

What it means

Environment's constructor throws IllegalArgumentException when dataSource is null (checked last, after id and transactionFactory). Without a DataSource the environment cannot open connections, so MyBatis rejects it immediately.

Source

Thrown at src/main/java/org/apache/ibatis/mapping/Environment.java:39

/**
 * @author Clinton Begin
 */
public final class Environment {
  private final String id;
  private final TransactionFactory transactionFactory;
  private final DataSource dataSource;

  public Environment(String id, TransactionFactory transactionFactory, DataSource dataSource) {
    if (id == null) {
      throw new IllegalArgumentException("Parameter 'id' must not be null");
    }
    if (transactionFactory == null) {
      throw new IllegalArgumentException("Parameter 'transactionFactory' must not be null");
    }
    this.id = id;
    if (dataSource == null) {
      throw new IllegalArgumentException("Parameter 'dataSource' must not be null");
    }
    this.transactionFactory = transactionFactory;
    this.dataSource = dataSource;
  }

  public static class Builder {
    private final String id;
    private TransactionFactory transactionFactory;
    private DataSource dataSource;

    public Builder(String id) {
      this.id = id;
    }

    public Builder transactionFactory(TransactionFactory transactionFactory) {
      this.transactionFactory = transactionFactory;
      return this;
    }

View on GitHub (pinned to 008069adb1)

Solutions

1. Provide a DataSource: e.g. UNPOOLED via org.apache.ibatis.datasource.unpooled.UnpooledDataSource or a pooled/HikariCP DataSource.
2. If using Environment.Builder, ensure .dataSource(ds) is called before .build().
3. Check upstream creation of the DataSource pool for swallowed exceptions (log them instead) so it never reaches Environment as null.

Example fix

// before
Environment env = new Environment.Builder("dev")
    .transactionFactory(new JdbcTransactionFactory())
    .build(); // dataSource never set -> null

// after
Environment env = new Environment.Builder("dev")
    .transactionFactory(new JdbcTransactionFactory())
    .dataSource(new UnpooledDataSource(driver, url, user, pass))
    .build();

DataSource ds = Objects.requireNonNull(dataSource, "DataSource creation failed");
new Environment.Builder("dev").transactionFactory(txf).dataSource(ds).build();

When it happens

Trigger: new Environment("dev", txFactory, null) or Environment.Builder.build() without calling dataSource(...) — commonly the DataSource failed to construct (DB URL typo causing a wrapped exception swallowed upstream) or the builder step was skipped.

Common situations: Programmatic configuration where the pooled DataSource creation code errored and the field stayed null; forgetting builder.dataSource(ds) when using Environment.Builder; unit tests building Configuration without a real DataSource.

Related errors

• dataSource cannot be null
• There was an error configuring JndiDataSourceTransactionPool
• Unknown DataSource property: ${propertyName}
• Parameter 'id' must not be null
• Parameter 'transactionFactory' must not be null

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