quarkusio/quarkus · error · IllegalArgumentException

Unsupported port format: ${port}

Error message

Unsupported port format: ${port}

What it means

ComposeServiceDefinition.getPorts() parses the ports section of a compose service definition into PortBinding objects. When an entry is neither the short 'HOST:CONTAINER[/PROTO]' form nor a recognized long-syntax mapping shape, it throws IllegalArgumentException('Unsupported port format: <port>').

Source

Thrown at extensions/devservices/deployment/src/main/java/io/quarkus/devservices/deployment/compose/ComposeServiceDefinition.java:85

                    String publishedStr = String.valueOf(published);
                    // Port ranges "8083-9000"
                    if (publishedStr.contains("-")) {
                        publishedStr = publishedStr.split("-")[0];
                    }
                    sb.append(publishedStr).append(":");
                }

                // target port "127.0.0.1:8080:80"
                sb.append(target);

                // protocol "127.0.0.1:8080:80/tcp"
                if (protocol != null) {
                    sb.append("/").append(protocol);
                }

                portString = sb.toString();
            } else {
                throw new IllegalArgumentException("Unsupported port format: " + port);
            }
            return PortBinding.parse(portString);
        })
                .map(PortBinding::getExposedPort)
                .collect(Collectors.toList());
    }

    public boolean hasHealthCheck() {
        return definitionMap.get("healthcheck") instanceof Map;
    }

    public Map<String, Object> getLabels() {
        Object labels = definitionMap.get("labels");
        if (labels instanceof List) {
            Map<String, Object> map = new HashMap<>();
            for (Object label : ((List<?>) labels)) {
                if (label instanceof String) {
                    String[] split = ((String) label).split("=");

View on GitHub (pinned to e1c734241f)

Solutions

1. Rewrite the ports entry in short syntax: '5432:5432' or '127.0.0.1:5432:5432' if the parser rejects it
2. Remove unsupported constructs (port ranges like '5432-5434:5432-5434') and list ports individually
3. Check the Quarkus version — upgrade, since newer parsers accept more long-syntax variants
4. Bypass compose port declaration by exposing the container port and letting DevServices map it dynamically

Example fix

# before (docker-compose.yml)
    ports:
      - target: 5432
        published: 15432
# after
    ports:
      - "15432:5432"

// validate ports section shape before use (short syntax expected)
for (Object p : servicePorts) {
    if (!(p instanceof String s) || !s.matches("([\"'])?\\d+:\\d+(/(tcp|udp))?([\"'])?"))
        throw new IllegalArgumentException("Use short port syntax like \"15432:5432\", got: " + p);
}

try {
    def.getPorts();
} catch (IllegalArgumentException e) {
    log.error("Fix docker-compose.yml ports entry: " + e.getMessage());
}

When it happens

Trigger: A docker-compose.yml ports entry uses a shape the parser does not understand — e.g. long-syntax objects with unexpected keys, malformed strings like '127.0.0.1::80' variants, host IP forms or ranges the simple parser rejects.

Common situations: Hand-written compose files with unusual port entries (IP-prefixed bindings, port ranges, named volumes accidentally under ports); machine-generated compose YAML using long syntax ('target: 5432, published: 5432') on a parser version that only supports short syntax.

Related errors

• Services have not been started yet
• Services named ${servicesToWaitFor} do not exist, but wait c
• Docker Compose not found. Is ${composeExecutable} on the PAT
• Failed to parse
• Cannot create a RunningDevServicesDatasource before the H2 d

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b6b1dc2fd7078841. Report an issue: GitHub.