apache/flink · error · IllegalArgumentException

fqdn is null

Error message

fqdn is null

What it means

NetUtils.getHostnameFromFQDN extracts the first label of a fully qualified domain name ('host.example.com' -> 'host'). It performs a null check on the input and throws IllegalArgumentException('fqdn is null') for a null argument, since it cannot derive a hostname from nothing.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/NetUtils.java:64

@Internal
public class NetUtils {

    private static final Logger LOG = LoggerFactory.getLogger(NetUtils.class);

    /** The wildcard address to listen on all interfaces (either 0.0.0.0 or ::). */
    private static final String WILDCARD_ADDRESS =
            new InetSocketAddress(0).getAddress().getHostAddress();

    /**
     * Turn a fully qualified domain name (fqdn) into a hostname. If the fqdn has multiple subparts
     * (separated by a period '.'), it will take the first part. Otherwise it takes the entire fqdn.
     *
     * @param fqdn The fully qualified domain name.
     * @return The hostname.
     */
    public static String getHostnameFromFQDN(String fqdn) {
        if (fqdn == null) {
            throw new IllegalArgumentException("fqdn is null");
        }
        int dotPos = fqdn.indexOf('.');
        if (dotPos == -1) {
            return fqdn;
        } else {
            return fqdn.substring(0, dotPos);
        }
    }

    /**
     * Converts a string of the form "host:port" into an {@link URL}.
     *
     * @param hostPort The "host:port" string.
     * @return The converted URL.
     */
    public static URL getCorrectHostnamePort(String hostPort) {
        return validateHostPortString(hostPort);
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Ensure the fqdn value is populated before the call — check the config source or lookup that produced it.
2. Add a null/empty check on the caller side with a meaningful error naming the missing setting.
3. Default to InetAddress.getLocalHost().getCanonicalHostName() when no explicit fqdn is configured.
4. Write a unit test passing null to lock in the expected failure mode.

Example fix

// before
String host = NetUtils.getHostnameFromFQDN(configHostname); // configHostname == null -> IAE

// after
Preconditions.checkNotNull(configHostname, "hostname not configured (set 'jobmanager.rpc.address')");
String host = NetUtils.getHostnameFromFQDN(configHostname);

if (fqdn == null || fqdn.isBlank()) {
    throw new IllegalArgumentException("fqdn must be set (check hostname config)");
}
String host = NetUtils.getHostnameFromFQDN(fqdn);

When it happens

Trigger: Calling NetUtils.getHostnameFromFQDN(null) — i.e. the fqdn string was never resolved (a config option unset, an InetAddress lookup returned null, or a nullable field passed through).

Common situations: Hostname configuration (e.g. jobmanager.rpc.address or similar) read as null because the property is absent; code that assumes InetAddress.getHostName() never returns null; refactors that made the fqdn source optional but kept the call unconditional.

Related errors

• The configured hostname is not valid
• Output file path may not be null.
• Delimiter must not be null
• Cannot register null class or serializer.
• Cannot register null type class.

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