{"record":{"id":"a7c0a93bb944d3ec","repo":"mybatis/mybatis-3","slug":"could-not-resolve-type-alias-cause","errorCode":null,"errorMessage":"Could not resolve type alias '{}'.  Cause: {}","messagePattern":"Could not resolve type alias '(.+?)'\\.  Cause: (.+?)","errorType":"exception","errorClass":"TypeException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java","lineNumber":127,"sourceCode":"\n  @SuppressWarnings(\"unchecked\")\n  // throws class cast exception as well if types cannot be assigned\n  public <T> Class<T> resolveAlias(String string) {\n    try {\n      if (string == null) {\n        return null;\n      }\n      // issue #748\n      String key = string.toLowerCase(Locale.ENGLISH);\n      Class<T> value;\n      if (typeAliases.containsKey(key)) {\n        value = (Class<T>) typeAliases.get(key);\n      } else {\n        value = (Class<T>) Resources.classForName(string);\n      }\n      return value;\n    } catch (ClassNotFoundException e) {\n      throw new TypeException(\"Could not resolve type alias '\" + string + \"'.  Cause: \" + e, e);\n    }\n  }\n\n  public void registerAliases(String packageName) {\n    registerAliases(packageName, Object.class);\n  }\n\n  public void registerAliases(String packageName, Class<?> superType) {\n    ResolverUtil<Class<?>> resolverUtil = new ResolverUtil<>();\n    resolverUtil.find(new ResolverUtil.IsA(superType), packageName);\n    Set<Class<? extends Class<?>>> typeSet = resolverUtil.getClasses();\n    for (Class<?> type : typeSet) {\n      // Ignore inner classes and interfaces (including package-info.java)\n      // Skip also inner classes. See issue #6\n      if (!type.isAnonymousClass() && !type.isInterface() && !type.isMemberClass()) {\n        registerAlias(type);\n      }\n    }","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java#L109-L145","documentation":"TypeAliasRegistry.resolveAlias lower-cases the input, checks the registered alias map, and as a last resort attempts Resources.classForName on the raw string. When both fail with ClassNotFoundException, it throws this TypeException: the string is neither a registered alias nor a loadable fully-qualified class name.","triggerScenarios":"A type/parameterType/resultType attribute like type=\"Usr\" (typo), an alias that was never registered, or a fully-qualified class name whose class is not on the classpath (missing dependency, wrong package).","commonSituations":"Typos in mapper XML; moving classes to a new package without updating XML; forgetting to register a package (<typeAliases><package name=\"...\"/></typeAliases>); fat-jar/classloader issues hiding domain classes.","solutions":["Fix the alias spelling or use the fully-qualified class name","Register the class or its package: <typeAliases><package name=\"com.example.domain\"/></typeAliases>","Verify the class is on the runtime classpath (dependency scope/classloader) when using a FQN"],"exampleFix":"// before\n<typeAlias alias=\"usr\" type=\"com.example.User\"/> ... <select resultType=\"user\">\n\n// after\n<typeAlias alias=\"user\" type=\"com.example.User\"/> ... <select resultType=\"user\">","handlingStrategy":"validation","validationCode":"String alias = \"user\";\nClass<?> c = configuration.getTypeAliasRegistry().resolveAlias(alias); // throws early with clear message\n// or pre-check: try { Class.forName(fqn); } catch (ClassNotFoundException e) { /* fix before boot */ }","typeGuard":null,"tryCatchPattern":"try { ... resolveAlias(...) } catch (TypeException e) { // fail fast at startup with which alias is unknown; do not swallow }","preventionTips":["Boot-time validation: resolve every type/alias referenced by mappers during application startup","Prefer fully-qualified names in XML; aliases only for a curated, registered set","Run a mapper-XML lint in CI that checks all resultType/parameterType values resolve"],"tags":["mybatis","type-alias","configuration","classpath"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}