apache/flink · error · IllegalArgumentException

Invalid cluster id "%s". The expected format is [0-9a-fA-F]{

Error message

Invalid cluster id "%s". The expected format is [0-9a-fA-F]{32}, e.g. fd72014d4c864993a2e5a9287b4a9c5d.

What it means

Thrown by ApplicationJobUtils.checkClusterId when ApplicationID.fromHexString(str) throws an IllegalArgumentException, meaning the cluster ID string does not conform to the expected 32-character hexadecimal format (e.g., fd72014d4c864993a2e5a9c5d). This check runs when application mode derives a fixed JobID from the HA cluster ID. The HA cluster ID must be a valid ApplicationID (32 hex chars) for the job ID derivation to succeed.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/deployment/application/ApplicationJobUtils.java:122

                            PipelineOptionsInternal.PIPELINE_FIXED_JOB_ID,
                            new JobID(
                                            Preconditions.checkNotNull(
                                                            configuration.get(
                                                                    HighAvailabilityOptions
                                                                            .HA_CLUSTER_ID))
                                                    .hashCode(),
                                            0)
                                    .toHexString());
                }
            }
        }
    }

    private static String checkClusterId(String str) {
        try {
            ApplicationID.fromHexString(str);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException(
                    "Invalid cluster id \""
                            + str
                            + "\". The expected format is [0-9a-fA-F]{32}, e.g. fd72014d4c864993a2e5a9287b4a9c5d.");
        }
        return str;
    }

    /**
     * Returns the job count limits for the given configuration.
     *
     * @param config The configuration to get the job count limits from
     * @return A tuple of (total job count limit, streaming job count limit)
     */
    public static Tuple2<Integer, Integer> getJobCountLimits(Configuration config) {
        if (config.get(DeploymentOptions.SUBMIT_FAILED_JOB_ON_APPLICATION_ERROR)) {
            // When enabled, this option ensures that if the application fails before any job is
            // submitted, a synthetic failed job is submitted for diagnostics. To provide a stable
            // and predictable job ID, only a single job is allowed in the main method. Therefore,

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Set high-availability.cluster-id to a 32-character hexadecimal string (e.g., generate with `uuidgen | tr -d '-'`)
2. Let Flink auto-generate the cluster ID by not setting high-availability.cluster-id explicitly
3. Use ApplicationID.fromHexString() in your deployment scripts to validate before passing the value

Example fix

# before
config.set("high-availability.cluster-id", "my-cluster")

# after
# use a 32-hex-char ID
config.set("high-availability.cluster-id", "fd72014d4c864993a2e5a9287b4a9c5d")
# or omit to auto-generate

// Validate cluster ID format before passing to Flink:
String clusterId = config.get(HighAvailabilityOptions.HA_CLUSTER_ID);
if (clusterId != null && !clusterId.matches("[0-9a-fA-F]{32}")) {
    throw new IllegalArgumentException(
        "Cluster ID must be 32 hex chars. Got: " + clusterId);
}

When it happens

Trigger: Setting high-availability.cluster-id to a non-hex or wrong-length string; using a custom cluster ID that doesn't match the ApplicationID hex format; the cluster ID is auto-generated incorrectly by a deployment plugin.

Common situations: Manual configuration of high-availability.cluster-id with a human-readable name instead of a hex hash; custom Kubernetes deployment scripts that set the cluster ID to the Kubernetes namespace or a short name.

Related errors

• Could not create the Dispatcher rpc endpoint.
• No cluster id was specified. Please specify a cluster to whi
• The configuration directory '{}', specified in the '{}' envi
• The configuration directory was not specified. Please specif
• No valid command-line found.

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