mybatis/mybatis-3 · error · TypeException

The parameter alias cannot be null

Error message

The parameter alias cannot be null

What it means

TypeAliasRegistry.registerAlias(alias, value) rejects a null alias with this TypeException because every registered mapping needs a non-null key (lower-cased at registration). It fires before any class resolution happens.

Source

Thrown at src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java:159

      // Skip also inner classes. See issue #6
      if (!type.isAnonymousClass() && !type.isInterface() && !type.isMemberClass()) {
        registerAlias(type);
      }
    }
  }

  public void registerAlias(Class<?> type) {
    String alias = type.getSimpleName();
    Alias aliasAnnotation = type.getAnnotation(Alias.class);
    if (aliasAnnotation != null) {
      alias = aliasAnnotation.value();
    }
    registerAlias(alias, type);
  }

  public void registerAlias(String alias, Class<?> value) {
    if (alias == null) {
      throw new TypeException("The parameter alias cannot be null");
    }
    // issue #748
    String key = alias.toLowerCase(Locale.ENGLISH);
    if (typeAliases.containsKey(key) && typeAliases.get(key) != null && !typeAliases.get(key).equals(value)) {
      throw new TypeException(
          "The alias '" + alias + "' is already mapped to the value '" + typeAliases.get(key).getName() + "'.");
    }
    typeAliases.put(key, value);
  }

  public void registerAlias(String alias, String value) {
    try {
      registerAlias(alias, Resources.classForName(value));
    } catch (ClassNotFoundException e) {
      throw new TypeException("Error registering type alias " + alias + " for " + value + ". Cause: " + e, e);
    }
  }

View on GitHub (pinned to 008069adb1)

Solutions

1. Pass a non-null alias string, or use registerAlias(Class) which defaults the alias to the simple name
2. Null-check aliases loaded from external config before registering
3. Annotate the class with @Alias("name") and register by class only

Example fix

// before
registry.registerAlias(aliasFromProps, User.class); // aliasFromProps is null

// after
registry.registerAlias(aliasFromProps != null ? aliasFromProps : "user", User.class);

Objects.requireNonNull(alias, "alias must not be null");
configuration.getTypeAliasRegistry().registerAlias(alias, type);

When it happens

Trigger: Calling configuration.getTypeAliasRegistry().registerAlias(null, SomeClass.class); or a registration path that derives the alias from an annotation/value that is absent and yields null.

Common situations: Programmatic configuration code passing a computed alias that turns out null; wrapping registerAlias in generic bootstrap code that reads aliases from a map/properties file with a missing key.

Related errors

• Error resolving class. Cause: {cause}
• Parameter 'id' must not be null
• Parameter 'transactionFactory' must not be null
• Parameter 'dataSource' must not be null
• ResultMaps must have an id

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