Ktor server port precedence between application.conf and PORT env var

Direct answer

In Ktor 2.x and 3.x, an explicitly supplied port in embeddedServer(..., port = ...) wins when it is present. Otherwise, a bare PORT environment variable does not automatically override ktor.deployment.port in application.conf. Environment variables enter Ktor configuration only through HOCON substitution, typically ${?PORT} for an optional fallback or ${PORT} for a required value.

Confirmed behavior versus likely explanation

Confirmed: Ktor does not auto-map PORT to ktor.deployment.port. A plain port = 8080 inside ktor.deployment { port = 8080 } remains effective unless HOCON substitutes an environment variable or code passes a port argument.

Likely: configuration resolution follows system properties over application.conf over environment variables, with the programmatic port parameter applied after environment loading. This nested merge order is not formally specified, so treat it as version-dependent until verified against your build.

Steps for this case

1. Inspect application.conf for ktor.deployment.port.
2. Run printenv PORT in the deployment shell to confirm whether the variable exists.
3. Look for HOCON substitution such as ktor.deployment.port = ${?PORT}. Without it, PORT is ignored.
4. If you call embeddedServer(Netty, port = 9090) { ... }, remove or condition the explicit argument when you want environment configuration to control the port.
5. After embeddedServer.start(), log application.environment.port to capture the effective port.

Containerized deployments

Set PORT in the container and reference it with optional fallback:

ktor.deployment.port = ${?PORT}

Provide a default in the same block if needed:

ktor.deployment.port = ${?PORT, 8080}

Do not rely on automatic detection. ${PORT} without the question mark fails at startup when the variable is missing.

Startup logs

Effective port emission is engine-dependent. Netty, Jetty, and Tomcat may log the bound address at different lifecycle points, and structured logging can omit it unless the port is added to the log context. Verify by opening a connection to the reported port or by reading application.environment.port programmatically.

Assumption: behavior is consistent between Ktor 2.x and 3.x. This draft should be reviewed against your exact Ktor version because the nested merge strategy is not formally specified.