mybatis/mybatis-3 · critical · DataSourceException

There was an error configuring JndiDataSourceTransactionPool

Error message

There was an error configuring JndiDataSourceTransactionPool. Cause: ${cause}

What it means

JndiDataSourceFactory throws DataSourceException when JNDI lookup of the configured DataSource fails with a NamingException. The factory reads the 'initial_context' and 'data_source' properties (and any prefixed 'env.' properties as JNDI environment), does InitialContext.lookup, and wraps any NamingException with the message 'There was an error configuring JndiDataSourceTransactionPool. Cause: <exception>'. The cause string identifies the exact JNDI problem (NameNotFoundException, NoInitialContextException, etc.).

Source

Thrown at src/main/java/org/apache/ibatis/datasource/jndi/JndiDataSourceFactory.java:59

  public void setProperties(Properties properties) {
    try {
      InitialContext initCtx;
      Properties env = getEnvProperties(properties);
      if (env == null) {
        initCtx = new InitialContext();
      } else {
        initCtx = new InitialContext(env);
      }

      if (properties.containsKey(INITIAL_CONTEXT) && properties.containsKey(DATA_SOURCE)) {
        Context ctx = (Context) initCtx.lookup(properties.getProperty(INITIAL_CONTEXT));
        dataSource = (DataSource) ctx.lookup(properties.getProperty(DATA_SOURCE));
      } else if (properties.containsKey(DATA_SOURCE)) {
        dataSource = (DataSource) initCtx.lookup(properties.getProperty(DATA_SOURCE));
      }

    } catch (NamingException e) {
      throw new DataSourceException("There was an error configuring JndiDataSourceTransactionPool. Cause: " + e, e);
    }
  }

  @Override
  public DataSource getDataSource() {
    return dataSource;
  }

  private static Properties getEnvProperties(Properties allProps) {
    Properties contextProperties = null;
    for (Entry<Object, Object> entry : allProps.entrySet()) {
      String key = (String) entry.getKey();
      String value = (String) entry.getValue();
      if (key.startsWith(ENV_PREFIX)) {
        if (contextProperties == null) {
          contextProperties = new Properties();
        }
        contextProperties.put(key.substring(ENV_PREFIX.length()), value);

View on GitHub (pinned to 008069adb1)

Solutions

1. Read the appended Cause in the exception message: NameNotFoundException means bad name, NoInitialContextException means no JNDI provider
2. Verify the exact JNDI name with your container's admin tools (e.g., WildFly/JBoss jboss-cli, Tomcat's context.xml Resource name) and fix the <property name="data_source"> value
3. For remote JNDI, supply 'env.' prefixed properties (env.initial_context_factory, env.provider_url, etc.) so InitialContext is constructed with them
4. If running standalone (no container), switch to a DataSourceFactory that creates connections directly (UNPOOLED/POOLED) instead of JNDI
5. Ensure the DataSource is bound before MyBatis builds its Configuration (deployment ordering in the app server)

Example fix

<!-- before: wrong name / no provider -->
<dataSource type="JNDI">
  <property name="data_source" value="java:comp/env/jbdc/Users"/> <!-- typo -->
</dataSource>

<!-- after -->
<dataSource type="JNDI">
  <property name="initial_context" value="java:comp/env"/>
  <property name="data_source" value="jdbc/UsersDS"/>
</dataSource>

// Optionally verify JNDI binding before MyBias builds the DataSource:
try {
  InitialContext ctx = new InitialContext();
  Object ds = ctx.lookup("java:comp/env/jdbc/UsersDS");
  if (!(ds instanceof DataSource)) throw new IllegalStateException("Not a DataSource");
} catch (NamingException e) {
  // bind/fix before proceeding
}

try {
  DataSourceFactory factory = new JndiDataSourceFactory();
  factory.setProperties(props);
} catch (DataSourceException e) {
  Throwable cause = e.getCause(); // NamingException with details
  // NameNotFound -> fix name; NoInitialContext -> run inside a container or set env.* properties
}

When it happens

Trigger: Configuring type="JNDI" in mybatis-config.xml with an initial_context/data_source name that does not exist in the application server's JNDI tree; running outside a container (standalone app or unit test) with no JNDI provider; misspelled JNDI names; missing 'env.' prefixed properties needed to reach a remote JNDI provider; DataSource not deployed/bound in the app server.

Common situations: Migrating an app from a full app server (where java:comp/env/jdbc/... is bound) to standalone/Spring Boot without a JNDI provider; typo in the JNDI name in XML config; the datasource not yet deployed at MyBatis initialization time; wrong env entries (INITIAL_CONTEXT_FACTORY/PROVIDER_URL) for remote JNDI.

Related errors

• Dots are not allowed in element names, please remove it from
• Unknown DataSource property: ${propertyName}
• Parameter 'dataSource' must not be null
• dataSource cannot be null
• Invalid bound statement (not found): {mapperInterface}.{meth

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