apache/flink · error · RuntimeException

Couldn't retrieve standalone cluster

Error message

Couldn't retrieve standalone cluster

What it means

Thrown by StandaloneClusterDescriptor.retrieve when the RestClusterClient constructor throws an exception (e.g., cannot resolve the JobManager REST address, port not reachable, or invalid configuration). The StandaloneClusterId is always the same singleton (StandaloneClusterId.getInstance()), so the failure is purely about connectivity to the configured REST endpoint. The original exception is wrapped as the cause of a RuntimeException.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/deployment/StandaloneClusterDescriptor.java:52

    public StandaloneClusterDescriptor(Configuration config) {
        this.config = Preconditions.checkNotNull(config);
    }

    @Override
    public String getClusterDescription() {
        String host = config.get(JobManagerOptions.ADDRESS, "");
        int port = config.get(JobManagerOptions.PORT, -1);
        return "Standalone cluster at " + host + ":" + port;
    }

    @Override
    public ClusterClientProvider<StandaloneClusterId> retrieve(
            StandaloneClusterId standaloneClusterId) throws ClusterRetrieveException {
        return () -> {
            try {
                return new RestClusterClient<>(config, standaloneClusterId);
            } catch (Exception e) {
                throw new RuntimeException("Couldn't retrieve standalone cluster", e);
            }
        };
    }

    @Override
    public ClusterClientProvider<StandaloneClusterId> deploySessionCluster(
            ClusterSpecification clusterSpecification) {
        throw new UnsupportedOperationException("Can't deploy a standalone cluster.");
    }

    @Override
    public ClusterClientProvider<StandaloneClusterId> deployApplicationCluster(
            final ClusterSpecification clusterSpecification,
            final ApplicationConfiguration applicationConfiguration) {
        throw new UnsupportedOperationException(
                "Application Mode not supported by standalone deployments.");
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Verify the JobManager is running and the REST endpoint is reachable: `curl http://<host>:8081/overview`
  2. Check that rest.address and rest.port in flink-conf.yaml match the actual JobManager REST endpoint
  3. Ensure no firewall or network policy blocks the REST port between the client and the JobManager

Example fix

// before (wrong address)
config.set(JobManagerOptions.ADDRESS, "wrong-host");
standaloneDescriptor.retrieve(StandaloneClusterId.getInstance());

// after
config.set(JobManagerOptions.ADDRESS, "correct-jm-host");
config.set(RestOptions.PORT, 8081);
standaloneDescriptor.retrieve(StandaloneClusterId.getInstance());
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate REST endpoint reachability before calling retrieve:
String host = config.get(JobManagerOptions.ADDRESS);
int port = config.get(RestOptions.PORT, 8081);
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 5000);
} catch (IOException e) {
    throw new IllegalStateException(
        "JobManager REST endpoint not reachable at " + host + ":" + port, e);
}

Try / catch

try {
    ClusterClientProvider<StandaloneClusterId> provider = descriptor.retrieve(id);
} catch (RuntimeException e) {
    if (e.getMessage().contains("Couldn't retrieve")) {
        Throwable cause = e.getCause();
        LOG.error("Standalone cluster unreachable: {}", cause.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling retrieve on a StandaloneClusterDescriptor when the JobManager REST endpoint at the configured address:port is unreachable; the REST port (rest.port, default 8081) is wrong or firewalled; the address resolves to a different host.

Common situations: Flink JobManager not started or crashed; REST port differs from the default; network policy or firewall blocks the REST port; DNS resolution failure for the configured jobmanager.rpc.address.

Related errors

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