mybatis/mybatis-3 · error · BuilderException

Error creating SqlSource for SqlProvider. Cause: {cause}

Error message

Error creating SqlSource for SqlProvider.  Cause: {cause}

What it means

Error "Error creating SqlSource for SqlProvider. Cause: {cause}" thrown in mybatis/mybatis-3.

Source

Thrown at src/main/java/org/apache/ibatis/builder/annotation/ProviderSqlSource.java:134

      if (candidateProviderMethod == null) {
        candidateProviderMethodName = candidateProviderMethodName.length() == 0 ? "provideSql"
            : candidateProviderMethodName;
        for (Method m : this.providerType.getMethods()) {
          if (candidateProviderMethodName.equals(m.getName())
              && CharSequence.class.isAssignableFrom(m.getReturnType())) {
            if (candidateProviderMethod != null) {
              throw new BuilderException("Error creating SqlSource for SqlProvider. Method '"
                  + candidateProviderMethodName + "' is found multiple in SqlProvider '" + this.providerType.getName()
                  + "'. Sql provider method can not overload.");
            }
            candidateProviderMethod = m;
          }
        }
      }
    } catch (BuilderException e) {
      throw e;
    } catch (Exception e) {
      throw new BuilderException("Error creating SqlSource for SqlProvider.  Cause: " + e, e);
    }
    if (candidateProviderMethod == null) {
      throw new BuilderException("Error creating SqlSource for SqlProvider. Method '" + candidateProviderMethodName
          + "' not found in SqlProvider '" + this.providerType.getName() + "'.");
    }
    this.providerMethod = candidateProviderMethod;
    this.paramNameResolver = new ParamNameResolver(configuration, this.providerMethod, mapperType);
    this.providerMethodParameterTypes = this.providerMethod.getParameterTypes();

    ProviderContext candidateProviderContext = null;
    Integer candidateProviderContextIndex = null;
    for (int i = 0; i < this.providerMethodParameterTypes.length; i++) {
      Class<?> parameterType = this.providerMethodParameterTypes[i];
      if (parameterType == ProviderContext.class) {
        if (candidateProviderContext != null) {
          throw new BuilderException(
              "Error creating SqlSource for SqlProvider. ProviderContext found multiple in SqlProvider method ("
                  + this.providerType.getName() + "." + providerMethod.getName()

View on GitHub (pinned to 008069adb1)

Solutions

1. Inspect the nested cause for the underlying reflection error (missing method, wrong signature, or inaccessible class).
2. Make sure the provider class has a public no-arg constructor and the provider method is accessible.
3. Verify the provider method signature matches the mapper method parameters or accepts ProviderContext.

When it happens

Trigger: Thrown at src/main/java/org/apache/ibatis/builder/annotation/ProviderSqlSource.java:134 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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