Docker "invalid IP address in add-host" in CI

By Daniel Zoghalchali·Latchkey

A --add-host=hostname:ip (or compose extra_hosts) injects an /etc/hosts entry. The daemon validates the IP, so a malformed address, an empty value from an unset variable, or a hostname in the IP slot is rejected.

What this error means

A docker run --add-host=... fails with Error response from daemon: invalid IP address in add-host: "...".

docker: Error response from daemon: invalid IP address in add-host: "api.internal:".

Common causes

An empty IP from an unset variable

An interpolated --add-host=api:$API_IP where API_IP is empty produces api: with no address.

A hostname where an IP is required

Putting a DNS name in the IP slot (api:db.internal) fails validation; --add-host needs a literal IP (or host-gateway).

A malformed IP literal

A typo like 10.0.0 or 999.1.1.1 is not a valid address.

How to fix it

Provide a valid IP literal

1. Use a real IPv4/IPv6 literal, or the special host-gateway token.

docker run --add-host=api.internal:10.1.2.3 myorg/app:ci
docker run --add-host=host.docker.internal:host-gateway myorg/app:ci

Guard interpolated host IPs

1. Fail fast if the IP variable is empty before constructing the flag.

: "${API_IP:?API_IP must be set}"
docker run --add-host="api.internal:$API_IP" myorg/app:ci

How to prevent it

• Validate interpolated IPs before passing them to --add-host.
• Use host-gateway for the host address instead of a hard-coded IP.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation