Failed to resolve 'kafka:9092': Name or service not known - docker / php-rdkafka

Failed to resolve 'kafka:9092': Name or service not known - docker / php-rdkafka

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Failed to resolve 'kafka:9092': Name or service not known - docker / php-rdkafka

When deploying a PHP application using php-rdkafka inside a Docker container, encountering a Failed to resolve 'kafka:9092': Name or service not known error is a classic networking pitfall. The stack trace clearly indicates that the underlying C library (librdkafka) cannot perform an A-record lookup for the hostname kafka. This isn't necessarily a problem with your PHP code logic; it is almost exclusively a DNS resolution failure within the container's network namespace.

The error message originates from the bootstrap process of the producer. Before sending any data, the client attempts to connect to the brokers listed in the configuration. In your specific setup, you are using addBrokers("kafka"). The application expects a service named kafka to exist in its internal DNS server (usually provided by Docker Compose), but that name cannot be resolved.

The Advertised Host vs. Internal Broker Name

The root of this issue often lies in the distinction between how a client connects and how the broker tells clients where to connect. In your docker-compose.yml, you have configured:

kafka:
  environment:
    KAFKA_ADVERTISED_HOST_NAME: kafka
    KAFKA_ADVERTISED_PORT: 9092

This configuration is correct for external access (e.g., from a host machine or a service outside the Docker network). When a client inside the same Docker network connects, it does not need the KAFKA_ADVERTISED_HOST_NAME to resolve the broker's internal IP. Instead, it relies on the hostname defined in the docker-compose.yml under the service name key.

However, there is a critical nuance regarding where the PHP container is running. The error log shows the process running as httpd_1. This implies your PHP application is served by an Apache HTTPD server inside a container named httpd. If this container is not part of the same user-defined network as the kafka service, DNS resolution will fail.

Diagnosing Network Isolation

In Docker Compose, services automatically join a shared network unless explicitly placed into separate networks. To ensure connectivity, verify that your docker-compose.yml structure aligns the containers. If your httpd service definition is missing or incomplete in your provided snippet, adding it to the same compose file ensures they share the default network.

If you are running these services separately or have split them into different networks, you must ensure the httpd container can query DNS for the name kafka. You can verify this by checking the /etc/resolv.conf inside your PHP container. If the nameserver is pointing to 127.0.0.53 (Docker's internal DNS), it should resolve the service name automatically provided they are on the same network.

Correcting the Broker Configuration

In your PHP code, you have:

$rk->addBrokers("kafka");

If the httpd container cannot resolve kafka, this call will fail immediately. You might consider using the IP address instead of the hostname as a temporary workaround to isolate the issue from DNS:

// Temporary workaround to bypass DNS issues
$rk->addBrokers("172.18.0.3"); // Replace with the actual internal IP of your Kafka container

However, relying on hardcoded IPs is not a production best practice because Docker IPs are ephemeral and change upon restart. The preferred solution is ensuring the hostname kafka resolves correctly.

Addressing Connection Refused vs. Name Resolution

You mentioned previously facing a Connection refused error. This is actually distinct from the current Name or service not known error.

  • Name or service not known: The client cannot find the broker's IP address. It happens at the DNS layer.
  • Connection refused: The client found the IP address, but the TCP handshake failed. This usually means the port is closed on the host or the KAFKA_ADVERTISED_HOST_NAME in the Kafka container points to an external interface that is not reachable from inside the Docker network (e.g., pointing to 0.0.0.0 vs a specific bridge IP, though modern Kafka images usually handle this gracefully if the advertised name matches the internal hostname).

If you switch to using the IP address and see Connection refused, it suggests the KAFKA_ADVERTISED_HOST_NAME configuration in your Kafka container might need adjustment for internal communication, or the port mapping is incorrect. For internal Docker network communication, setting KAFKA_ADVERTISED_LISTENERS to listen on the internal interface is often safer than relying solely on ADVERTISED_HOST_NAME.

Final Verification Steps

Before concluding that the code is flawed, inspect your docker-compose.yml again. Ensure there are no typos in the service name kafka. If you have defined a custom network, ensure both services belong to it:

networks:
  default:
    driver: bridge

If you move the PHP application to a dedicated network segment, update your addBrokers call to use the FQDN or the specific IP of that network. The error message is explicit: the resolver returned failure. Fixing the Docker networking topology is the only way to resolve this without modifying the broker's advertised hostname for internal traffic.

If you are managing a larger infrastructure where consistent broker discovery is required across multiple environments, consider using an external DNS service or a Consul/Kubernetes CoreDNS setup, but for standard Docker Compose setups, ensuring all services share the default bridge network and verifying the KAFKA_ADVERTISED_HOST_NAME matches the container name in the compose file is the definitive fix.

Our network