apache/beam · error · java.lang.RuntimeException

A transform cannot be initiated using the provided config…

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.

Solutions

1. Verify the parameters sent in the transform payload match what the TransformPayloadTranslator expects
2. Check that both sides of the cross-language pipeline use compatible Beam versions
3. Inspect fromConfigRow of the translator to see which fields are required
4. 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'}

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

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

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

• Failed to build transform
• Conflicting registrations for
• Could not find a transform with the ID
• Error decoding payload
• error in startAutomatedJavaExpansionService

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

Appendix: 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)