mybatis/mybatis-3 · error · IllegalArgumentException

null is not a valid Language Driver

Error message

null is not a valid Language Driver

What it means

LanguageDriverRegistry.register(Class) registers a scripting LanguageDriver class by instantiating it. Passing a null Class is meaningless — there is no driver to register — so it fails fast with IllegalArgumentException. This is a programming/API-contract error, not a configuration data issue.

Source

Thrown at src/main/java/org/apache/ibatis/scripting/LanguageDriverRegistry.java:32

 *    limitations under the License.
 */
package org.apache.ibatis.scripting;

import java.util.HashMap;
import java.util.Map;

/**
 * @author Frank D. Martinez [mnesarco]
 */
public class LanguageDriverRegistry {

  private final Map<Class<? extends LanguageDriver>, LanguageDriver> languageDriverMap = new HashMap<>();

  private Class<? extends LanguageDriver> defaultDriverClass;

  public void register(Class<? extends LanguageDriver> cls) {
    if (cls == null) {
      throw new IllegalArgumentException("null is not a valid Language Driver");
    }
    languageDriverMap.computeIfAbsent(cls, k -> {
      try {
        return k.getDeclaredConstructor().newInstance();
      } catch (Exception ex) {
        throw new ScriptingException("Failed to load language driver for " + cls.getName(), ex);
      }
    });
  }

  public void register(LanguageDriver instance) {
    if (instance == null) {
      throw new IllegalArgumentException("null is not a valid Language Driver");
    }
    Class<? extends LanguageDriver> cls = instance.getClass();
    if (!languageDriverMap.containsKey(cls)) {
      languageDriverMap.put(cls, instance);
    }

View on GitHub (pinned to 008069adb1)

Solutions

1. Pass the actual driver class: registry.register(XmlLanguageDriver.class)
2. Fix the upstream class-name resolution so it never yields null (fail on Class.forName errors instead of swallowing them)
3. Add a null check with a meaningful error before calling register

Example fix

// before
Class<? extends LanguageDriver> cls = lookup(name); // returns null on bad name
registry.register(cls);

// after
Class<? extends LanguageDriver> cls = Objects.requireNonNull(lookup(name), "Unknown language driver: " + name);
registry.register(cls);

Class<? extends LanguageDriver> cls = resolveDriverClass(name);
java.util.Objects.requireNonNull(cls, "Unknown language driver class: " + name);
registry.register(cls);

When it happens

Trigger: languageDriverRegistry.register((Class<? extends LanguageDriver>) null); configuration XML/programmatic setup that resolves a driver class name to null (class not found and silently swallowed) and then registers the null result.

Common situations: Custom Configuration subclasses or bootstraps that register drivers dynamically; typo'd class names where lookup code returns null instead of failing; test harnesses passing null by accident.

Related errors

• Failed to load language driver for " + cls.getName()
• Dynamic content is not allowed when using RAW language
• Invalid bound statement (not found): {mapperInterface}.{meth
• Type {type} is not known to the MapperRegistry.
• Error resolving JdbcType. Cause: {cause}

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