apache/flink · critical · RuntimeException

Can not register process function transformation translator.

Error message

Can not register process function transformation translator.

What it means

ExecutionEnvironmentImpl's static initializer wraps any failure of DataStreamV2SinkTransformationTranslator.registerSinkTransformationTranslator() in RuntimeException. That registration uses reflection because flink-datastream does not hard-depend on the process-function module, so linkage/classloading problems surface here. Because it fails in a static block, callers actually see ExceptionInInitializerError and the class becomes unusable (NoClassDefFoundError on later uses).

Source

Thrown at flink-datastream/src/main/java/org/apache/flink/datastream/impl/ExecutionEnvironmentImpl.java:98

    private final Configuration configuration;

    private final ClassLoader userClassloader;

    private final PipelineExecutorServiceLoader executorServiceLoader;

    /**
     * The environment of the context (local by default, cluster if invoked through command line).
     */
    private static ExecutionEnvironmentFactory contextEnvironmentFactory = null;

    static {
        try {
            // All transformation translator must be put to a map in StreamGraphGenerator, but
            // streaming-java is not depend on process-function module, using reflect to handle
            // this.
            DataStreamV2SinkTransformationTranslator.registerSinkTransformationTranslator();
        } catch (Exception e) {
            throw new RuntimeException(
                    "Can not register process function transformation translator.", e);
        }
    }

    /**
     * Create and return an instance of {@link ExecutionEnvironment}.
     *
     * <p>IMPORTANT: The method is only expected to be called by {@link ExecutionEnvironment} via
     * reflection, so we must ensure that the package path, class name and the signature of this
     * method does not change.
     */
    public static ExecutionEnvironment newInstance() {
        if (contextEnvironmentFactory != null) {
            return contextEnvironmentFactory.createExecutionEnvironment(new Configuration());
        } else {
            final Configuration configuration = new Configuration();
            configuration.set(DeploymentOptions.TARGET, "local");
            configuration.set(DeploymentOptions.ATTACHED, true);

View on GitHub (pinned to 2f3c205e92)

Solutions

Align all flink-* artifacts in the job to the exact cluster Flink version (mvn dependency:tree | grep flink)
Ensure flink-datastream (and the process-function translator it reflects to) ships in the job jar or is provided by the dist
Rebuild the fat jar without relocation of org.apache.flink packages
Inspect the original cause in the stack trace — it names the exact missing class behind the wrapper RuntimeException

Example fix

# before: mixed versions
flink-streaming-java:1.20.0, flink-datastream:2.0-SNAPSHOT -> ExceptionInInitializerError

# after: pin all to the running distribution's version
<flink.version>2.1.0</flink.version>  <!-- single property used by every flink-* dep -->

Defensive patterns

Strategy: try-catch

Validate before calling

// fail fast at startup with a readable diagnosis instead of ExceptionInInitializerError deep in job submission
try {
    Class.forName("org.apache.flink.datastream.impl.ExecutionEnvironmentImpl");
} catch (ExceptionInInitializerError | NoClassDefFoundError e) {
    throw new IllegalStateException("flink-datastream runtime mismatch: check that all flink-* jars match the cluster version", e.getCause());
}

Try / catch

catch (ExceptionInInitializerError e) { Throwable root = e.getCause(); /* root names the missing/mismatched class — report it, then fix classpath versions; retrying is pointless */ }

Prevention

Pin every flink-* dependency to the exact version of the running distribution via a single version property
Do not relocate or exclude org.apache.flink packages when shading job jars
Run mvn dependency:tree and check for duplicate flink-datastream/flink-streaming-java artifacts
Read the wrapped cause — it identifies the precise missing class behind the registration failure

When it happens

Trigger: Loading ExecutionEnvironmentImpl when the process-function translator classes (or their dependencies like flink-streaming-java internals) are missing or version-mismatched on the classpath; shaded/partial deployments that drop the reflected classes; mixed Flink versions in one job jar.

Common situations: Building a thin job jar against one Flink version and running on a cluster with another; excluding transitive flink-datastream/process-function dependencies; fat jars that relocate or omit org.apache.flink classes the reflection lookup needs.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/c32c11a4203198d0. Report an issue: GitHub.