apache/beam · error · java.lang.RuntimeException

A transform cannot be initiated using the provided config ro

Error message

A transform cannot be initiated using the provided config row %s and the TransformPayloadTranslator %s

What it means

ExpansionService.getTransform() throws this RuntimeException when a payloadTranslator.fromConfigRow(configRow, options) returns null, meaning the TransformPayloadTranslator recognized the URN but could not build a PTransform from the supplied config Row. The config row decoded successfully, but it is not acceptable to the translator.

Source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionService.java:273

    }

    @Override
    public PTransform<InputT, OutputT> getTransform(
        RunnerApi.FunctionSpec spec, PipelineOptions options) {
      if (isSchemaTransform()) {
        return ExpansionServiceSchemaTransformProvider.of().getTransform(spec, options);
      } else {
        try {
          ExternalConfigurationPayload payload =
              ExternalConfigurationPayload.parseFrom(spec.getPayload());
          Row configRow =
              RowCoder.of(SchemaTranslation.schemaFromProto(payload.getSchema()))
                  .decode(new ByteArrayInputStream(payload.getPayload().toByteArray()));
          PTransform transformFromRow = payloadTranslator.fromConfigRow(configRow, options);
          if (transformFromRow != null) {
            return transformFromRow;
          } else {
            throw new RuntimeException(
                String.format(
                    "A transform cannot be initiated using the provided config row %s and the"
                        + " TransformPayloadTranslator %s",
                    configRow, payloadTranslator));
          }
        } catch (Exception e) {
          throw new RuntimeException(
              String.format(
                  "Failed to build transform %s from spec %s: %s",
                  spec.getUrn(), spec, e.getMessage()),
              e);
        }
      }
    }

    @Override
    public InputT createInput(Pipeline p, Map<String, PCollection<?>> inputs) {
      if (isSchemaTransform()) {

View on GitHub (pinned to 12126d8942)

Solutions

Verify the parameters sent in the transform payload match what the TransformPayloadTranslator expects
Check that both sides of the cross-language pipeline use compatible Beam versions
Inspect fromConfigRow of the translator to see which fields are required
Log/dump the configRow to compare expected vs actual fields

Example fix

// before: payload missing a required field
payload = {'query': 'SELECT 1'}  # translator also requires 'driver'
// after
payload = {'query': 'SELECT 1', 'driver': 'postgresql'}

Defensive patterns

Strategy: validation

Validate before calling

// verify required config fields exist before expansion
if (!configRow.getSchema().getFieldNames().containsAll(requiredFields)) throw new IllegalArgumentException("missing config fields");

Try / catch

try { service.getTransform(spec, options); } catch (RuntimeException e) { if (e.getMessage().contains("transform cannot be initiated")) { /* fix payload config row fields */ } throw e; }

Prevention

Match config payload fields exactly to the translator's expectations
Keep cross-language pipeline sides on compatible Beam versions
Add integration tests that expand every external transform you use

When it happens

Trigger: Calling getTransform with a FunctionSpec whose payload decodes to a config Row that fromConfigRow rejects (missing/invalid fields), causing it to return null instead of a PTransform.

Common situations: Cross-language pipeline where the Python side sends config parameters the Java translator does not expect; schema evolved between SDK versions so required fields are absent; typo in a config parameter name.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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