apache/dolphinscheduler · error · IllegalArgumentException

The specified network interface: + specifiedNetworkInterface

Error message

The specified network interface: + specifiedNetworkInterfaceName + is not found

What it means

NetUtils.suitableNetworkInterface() filters the list of valid network interfaces down to the one named by the 'network.interface.specified' configuration. If no interface with that display name exists on the machine, the filter yields an empty list and this IllegalArgumentException is thrown instead of returning a wrong/ambiguous address.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/NetUtils.java:230

                        return !(networkInterface == null
                                || networkInterface.isLoopback()
                                || networkInterface.isVirtual()
                                || !networkInterface.isUp());
                    } catch (SocketException e) {
                        log.warn("ValidNetworkInterfaces exception", e);
                        return false;
                    }
                })
                .collect(Collectors.toList());

        // Use the specified network interface if set
        String specifiedNetworkInterfaceName = specifyNetworkInterfaceName();
        if (StringUtils.isNotBlank(specifiedNetworkInterfaceName)) {
            validNetworkInterfaces = validNetworkInterfaces.stream()
                    .filter(networkInterface -> specifiedNetworkInterfaceName.equals(networkInterface.getDisplayName()))
                    .collect(Collectors.toList());
            if (CollectionUtils.isEmpty(validNetworkInterfaces)) {
                throw new IllegalArgumentException(
                        "The specified network interface: " + specifiedNetworkInterfaceName + " is not found");
            }
            log.info("Use the specified network interface: {} -> {}", specifiedNetworkInterfaceName,
                    validNetworkInterfaces);
        }

        Set<String> restrictNetworkInterfaceName = restrictNetworkInterfaceName();
        if (CollectionUtils.isNotEmpty(restrictNetworkInterfaceName)) {
            validNetworkInterfaces = validNetworkInterfaces.stream()
                    .filter(validNetworkInterface -> !restrictNetworkInterfaceName
                            .contains(validNetworkInterface.getDisplayName()))
                    .collect(Collectors.toList());
        }
        return filterByNetworkPriority(validNetworkInterfaces);
    }

    /**
     * Get the suitable {@link InetAddress}

View on GitHub (pinned to 02eac45a1b)

Solutions

Run 'ip a' (Linux) or 'ifconfig -a' and set the config to an exact interface display name (e.g. ens33, en0), or remove the config to auto-select
Check for typos/case: the comparison is exact against NetworkInterface.getDisplayName(), not getName()
If running in a container, use the container's interface name (usually eth0) rather than the host's

Example fix

// before (application.yaml)
network.interface.preferred: eth0   # not found on host
// after
network.interface.preferred: ens33  # or remove the key to auto-detect

Defensive patterns

Strategy: validation

Validate before calling

String name = specifyNetworkInterfaceName();
if (StringUtils.isNotBlank(name)) {
    boolean exists = Collections.list(NetworkInterface.getNetworkInterfaces()).stream()
        .anyMatch(ni -> name.equals(ni.getDisplayName()));
    if (!exists) throw new IllegalArgumentException("Unknown NIC: " + name);
}

Try / catch

try { suitableNetworkInterface(); } catch (IllegalArgumentException e) { log.error("NIC config invalid, falling back to auto-detect", e); /* fall back to default interface */ }

Prevention

List actual interface names with 'ip a' before configuring
Avoid hardcoding NIC names in shared configs; use environment-specific values
Prefer leaving the property unset to allow auto-selection

When it happens

Trigger: Setting the network interface config property (dolphin.network.interface.preferred / specifyNetworkInterfaceName) to a name that does not match any NetworkInterface.getDisplayName() on the host, e.g. 'eth0' on a system where interfaces are named 'ens33' or 'en0'.

Common situations: Copying a config from one machine to another with different NIC naming schemes; Docker/Kubernetes container interface names differing from the host; typos in the config value; renamed interfaces after an OS upgrade.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/0defecaaf3d5f633. Report an issue: GitHub.