apache/beam · error · java.lang.RuntimeException

Failed to build transform %s from spec %s: %s

Error message

Failed to build transform %s from spec %s: %s

What it means

ExpansionService.getTransform() wraps any exception raised while building a transform from a config-row-based spec into this RuntimeException, preserving the original as cause. The message includes the URN, the full spec, and the original exception message.

Source

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

      } 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()) {
        return (InputT) ExpansionServiceSchemaTransformProvider.of().createInput(p, inputs);
      } else {
        return TransformProvider.super.createInput(p, inputs);
      }
    }

    @Override

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the 'Caused by' exception - this message only summarizes the failure
2. Verify the spec's URN matches a translator available in the expansion service
3. Validate the payload bytes and schema proto are consistent with the translator's expectations
4. Ensure all connector dependencies are present in the expansion service classpath

Example fix

// before: expansion service without JDBC driver dependency
java -jar expansion-service.jar
// after: add driver to classpath
java -cp expansion-service.jar:postgresql-42.7.3.jar org.apache.beam.sdk.expansion.service.ExpansionService ...

try { transform = service.getTransform(spec, options); } catch (RuntimeException e) { log.error("Expansion failed for URN {}: {}", spec.getUrn(), e.getCause(), e); throw e; }

When it happens

Trigger: Any Exception thrown inside the try block - schema/payload decoding errors, fromConfigRow failures, or translator construction errors - while resolving a transform by URN during pipeline expansion.

Common situations: Malformed payload schema proto; config Row deserialization failing; translator throwing during PTransform construction (bad connection params, missing files); URN belonging to a translator whose dependencies are missing on the classpath.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• A transform cannot be initiated using the provided config ro
• Failed to parse secret option
• Could not find a transform with the ID
• expansion service error: %s
• Failed to validate transform %s

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