baomidou/mybatis-plus · error · RuntimeException

Unable to retrieve localhost

Error message

Unable to retrieve localhost

What it means

NetUtils tries to find the machine's non-loopback address (for identifier/trace purposes) and, failing that, falls back to InetAddress.getLocalHost(). If the OS cannot resolve a localhost entry (no /etc/hosts mapping, DNS misconfiguration), the UnknownHostException is rethrown as RuntimeException('Unable to retrieve localhost'). It is an environment problem, not a logic problem.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/toolkit/NetUtils.java:78

                            if (address instanceof Inet4Address
                                && !address.isLoopbackAddress()
                                && isPreferredAddress(address)) {
                                result = address;
                            }
                        }
                    }
                }
            }
        } catch (IOException exception) {
            LOG.error("Cannot get first non-loopback address", exception);
        }
        if (result != null) {
            return result;
        }
        try {
            return InetAddress.getLocalHost();
        } catch (UnknownHostException e) {
            throw new RuntimeException("Unable to retrieve localhost");
        }
    }

    boolean isPreferredAddress(InetAddress address) {
        final List<String> preferredNetworks = this.netProperties.getPreferredNetworks();
        if (preferredNetworks.isEmpty()) {
            return true;
        }
        for (String regex : preferredNetworks) {
            final String hostAddress = address.getHostAddress();
            if (hostAddress.matches(regex) || hostAddress.startsWith(regex)) {
                return true;
            }
        }
        return false;
    }

    boolean ignoreInterface(String interfaceName) {

View on GitHub (pinned to bf67d90747)

Solutions

1. In Docker/k8s, ensure the container hostname resolves: add it to /etc/hosts (docker run --add-host, or an initContainer/entrypoint appending '127.0.0.1 $HOSTNAME').
2. On VMs/bare metal, add '<ip> <hostname>' to /etc/hosts so getLocalHost() resolves.
3. Check any JVM security policy / SecurityManager that might block local address resolution and grant it or remove it.
4. If neither is possible, avoid the code path that triggers NetUtils (identifier generation needing a local address) and supply the identifier explicitly.

Example fix

# before: container hostname unresolvable -> RuntimeException on getLocalHost()
docker run myapp:latest

# after: make the hostname resolvable
docker run --add-host="$(hostname):127.0.0.1" myapp:latest
# or in the entrypoint:
echo "127.0.0.1 $(hostname)" >> /etc/hosts

boolean localResolvable;
try {
    InetAddress.getLocalHost();
    localResolvable = true;
} catch (UnknownHostException e) {
    localResolvable = false;
}
if (!localResolvable) { /* fix /etc/hosts or container hostname before starting app */ }

try {
    String addr = NetUtils.getLocalHost();
} catch (RuntimeException e) {
    // fall back to a configured identifier
    log.warn("local address unresolvable; using configured node id", e);
}

When it happens

Trigger: Running on a host where getLocalHost() throws UnknownHostException: hostname not mapped in /etc/hosts (common in minimal Docker/alpine images or Kubernetes pods with randomized hostnames), or a security manager/JVM security policy blocks InetAddress.getLocalHost().

Common situations: Docker containers with hostnames absent from /etc/hosts; hardened containers where networking is restricted; CI runners with unusual network setups; k8s pods with generated hostnames.

Related errors

• Environment declaration requires a TransactionFactory.
• Environment declaration requires a DataSourceFactory.
• No environment specified.
• Environment requires an id attribute.

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/1f0b305e1a80cc18. Report an issue: GitHub.