apache/flink · error · FlinkException

Could not instantiate class '%s' of type '%s'. Please make s

Error message

Could not instantiate class '%s' of type '%s'. Please make sure that this class is on your class path.

What it means

InstantiationUtil.instantiate(className, targetType, classLoader) does Class.forName(className, false, classLoader).asSubclass(targetType); a ClassNotFoundException is wrapped in FlinkException with 'Could not instantiate class ... Please make sure that this class is on your class path.' Despite the wording, this is a class-not-found problem: the named class is not loadable by the supplied classloader.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/InstantiationUtil.java:255

    /**
     * Creates a new instance of the given class name and type using the provided {@link
     * ClassLoader}.
     *
     * @param className of the class to load
     * @param targetType type of the instantiated class
     * @param classLoader to use for loading the class
     * @param <T> type of the instantiated class
     * @return Instance of the given class name
     * @throws FlinkException if the class could not be found
     */
    public static <T> T instantiate(
            final String className, final Class<T> targetType, final ClassLoader classLoader)
            throws FlinkException {
        final Class<? extends T> clazz;
        try {
            clazz = Class.forName(className, false, classLoader).asSubclass(targetType);
        } catch (ClassNotFoundException e) {
            throw new FlinkException(
                    String.format(
                            "Could not instantiate class '%s' of type '%s'. Please make sure that this class is on your class path.",
                            className, targetType.getName()),
                    e);
        }

        return instantiate(clazz);
    }

    /**
     * Creates a new instance of the given class.
     *
     * @param <T> The generic type of the class.
     * @param clazz The class to instantiate.
     * @param castTo Optional parameter, specifying the class that the given class must be a
     *     subclass off. This argument is added to prevent class cast exceptions occurring later.
     * @return An instance of the given class.
     * @throws RuntimeException Thrown, if the class could not be instantiated. The exception

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the class really exists in the executed jar: `jar tf your.jar | grep <ClassName>`
2. Add the missing dependency to the job jar, or mark it provided vs included correctly so it lands in the runtime classpath
3. If shading renamed packages, update the configured class name to the relocated FQCN or add a relocation rule keeping the original name
4. Check the classloader you pass — with child-first resolution the class must be reachable from the user-code jar's loader

Example fix

# before
pipeline.className: com.acme.LegacyFunction  # moved to com.acme.v2.LegacyFunction in 2.x
# after
pipeline.className: com.acme.v2.LegacyFunction

try {
    Class.forName(className, false, userClassLoader);
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Configured class not on classpath: " + className, e);
}

try { T t = InstantiationUtil.instantiate(cls, type, loader); } catch (FlinkException e) { /* report jar/classpath mismatch with className */ }

When it happens

Trigger: Configuring a class by name (e.g. a plugin/connector/utility factory) that is absent from the user jar or the classloader passed in; shade/relocation renaming the class; wrong artifact version where the class moved packages.

Common situations: Pipeline options referencing a class that lives in an unshaded optional dependency; fat-jar shading renaming packages so the configured FQCN no longer exists; user-code classloader (child-first) hiding a class that only exists in the parent.

Related errors

• Bad syntax for classpath: {}
• Multiple compatible client factories found for: {}.
• No ClusterClientFactory found. If you were targeting a Yarn
• Could not load class for serialization config
• Unknown class resolution order: {resolveOrder}

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