Spring Boot "Caused by: java.net.UnknownHostException" in CI

DNS resolution failed: the JVM could not turn a hostname into an address. In CI this usually means a URL points at a Docker-network alias or an internal host that does not exist on the runner.

What this error means

Startup or a client call fails with "Caused by: java.net.UnknownHostException: db" (or a broker/service name) that resolves fine in your local compose network.

Caused by: java.net.UnknownHostException: postgres
	at java.base/java.net.InetAddress.getAllByName0(...)

Common causes

A compose-network hostname used outside that network

The URL uses a service alias like postgres or db that only resolves inside docker-compose, not on the plain runner.

An internal host not reachable from CI

A corporate or VPC-only hostname does not resolve on GitHub-hosted runners.

How to fix it

Use the host the runner can resolve

For a service container mapped to the runner, use localhost and the published port.

env:
  SPRING_DATASOURCE_URL: jdbc:postgresql://localhost:5432/app

Run the app inside the same network as the service

If you must use the alias, run the job (or the app) in the same Docker network so the name resolves.

container:
  image: eclipse-temurin:21
services:
  postgres:
    image: postgres:16

How to prevent it

• Match hostnames to how services are exposed in CI (localhost vs network alias).
• Externalize hosts so CI can override them, do not hardcode compose names.
• Prefer Testcontainers, which injects a resolvable host and port.

Related guides