apache/beam · error · RuntimeException

Creator parameter ${paramName} Doesn't correspond to a schem

Error message

Creator parameter ${paramName} Doesn't correspond to a schema field. Make sure that you are compiling with -parameters parameter to include constructor parameter information in class files.

What it means

When generating a from-row creator, Beam matches each creator method/constructor parameter name to a schema field. If a parameter name cannot be resolved to any field (including after trimming AutoValue's '$' suffix), it throws RuntimeException. The message specifically hints at the -parameters javac flag because without it parameter names are erased and become arg0, arg1, etc.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/ByteBuddyUtils.java:1622

            fieldsByJavaClassMember.put(name, i);
          }
        }
      }

      fieldMapping = Maps.newHashMap();
      for (int i = 0; i < parameters.size(); ++i) {
        Parameter parameter = parameters.get(i);
        String paramName = parameter.getName();
        Integer index = fieldsByLogicalName.get(paramName);
        if (index == null) {
          index = fieldsByJavaClassMember.get(paramName);
        }
        if (index == null && paramName.endsWith("$")) {
          // AutoValue appends "$" in some cases
          index = fieldsByJavaClassMember.get(paramName.substring(0, paramName.length() - 1));
        }
        if (index == null) {
          throw new RuntimeException(
              "Creator parameter "
                  + paramName
                  + " Doesn't correspond to a schema field."
                  + " Make sure that you are compiling with -parameters parameter to include"
                  + " constructor parameter information in class files.");
        }
        fieldMapping.put(i, index);
      }
    }

    @Override
    public InstrumentedType prepare(InstrumentedType instrumentedType) {
      return instrumentedType;
    }

    @Override
    public ByteCodeAppender appender(final Target implementationTarget) {
      return (methodVisitor, implementationContext, instrumentedMethod) -> {

View on GitHub (pinned to 12126d8942)

Solutions

Enable the -parameters javac flag in your build (maven-compiler-plugin <parameters>true</parameters> or Gradle compileJava { options.compilerArgs << '-parameters' }).
Rename creator parameters to exactly match schema field names.
Rebuild and clean stale class files after changing compiler options.
Disable code obducers/minifiers that strip parameter names for schema classes.

Example fix

// before (pom.xml)
<maven.compiler.source>1.8</maven.compiler.source>
// after
<properties><maven.compiler.parameters>true</maven.compiler.parameters></properties>
// or Gradle: tasks.withType(JavaCompile) { options.compilerArgs.add("-parameters") }

Defensive patterns

Strategy: validation

Validate before calling

for (java.lang.reflect.Constructor<?> c : MyType.class.getDeclaredConstructors()) { for (java.lang.reflect.Parameter p : c.getParameters()) { if (p.isNamePresent() == false) throw new IllegalStateException("Compile with -parameters"); } }

Try / catch

try { beamConvert(rows, MyType.class); } catch (RuntimeException e) { if (e.getMessage().contains("-parameters")) { /* rebuild with -parameters */ } throw e; }

Prevention

Add -parameters to javac options in every module's build config.
Verify with a startup check that Parameter.isNamePresent() is true for schema classes.
Never obfuscate schema classes (keep -dontobfuscate for them in ProGuard/R8).

When it happens

Trigger: Compiling without javac -parameters so reflection sees arg0/arg1 names that match no schema field; a creator parameter whose name differs from the schema field name; AutoValue '$'-suffixed names that still don't map after trimming.

Common situations: Maven/Gradle builds missing the -parameters compiler flag; renaming a schema field without renaming the creator parameter; using minified/obfuscated builds where parameter names are stripped.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/d500f57260443e0d. Report an issue: GitHub.