Gatling baseUrl works locally but fails in production containers: is an explicit scheme required?

Short answer: yes, the scheme is required

Gatling's http.baseUrl(...) (Gatling 3.x, Java DSL) expects an absolute URI including a scheme, such as http://localhost:8080. Gatling does not validate, normalize, or auto-correct the value; it is passed to the underlying HTTP client, which needs the scheme to select a protocol handler and open a connection. A value like localhost:8080 is not a usable absolute URI, so request construction or connection fails.

Likely explanation vs. confirmed facts

Confirmed by behavior: the missing scheme is the defect. Fix that first.

Likely, not confirmed: the working-directory theory is probably a misconception. Relative-URI resolution against the JVM working directory is not how Gatling's HTTP client builds request URLs. The more plausible reason it "works locally" is an environmental difference — for example, a local run actually receiving a different value (an IDE run configuration, a Maven/Gradle default, or a shell variable) than the container. Verify by logging the resolved value at startup in both environments.

Trailing slash

Be deliberate about it. Gatling concatenates the base URL with the path passed to http(...). A base of http://host:8080/api combined with request path /users can drop the api segment depending on how paths are joined. The safe convention: end the base URL with a trailing slash and start request paths without a leading slash ("users"). Mandate one convention in your team rather than mixing both.

Per-environment overrides

Yes — externalizing is the intended pattern. The common approach is a system property with a local default:

HttpProtocolBuilder httpProtocol = http
    .baseUrl(System.getProperty("baseUrl", "http://localhost:8080/"));

Then pass it in CI or the container:

JAVA_OPTS="-DbaseUrl=https://api.internal.example/" gatling.sh

Environment variables via System.getenv("BASE_URL") or a Typesafe Config entry work equally well; the key point is that simulation code stays identical across environments.

Verification

1. Add the scheme and trailing slash, then rerun in the container.
2. Log the resolved base URL at simulation start in both environments to confirm they actually receive the same value.
3. If failures persist after the scheme fix, capture the exact exception: a MalformedURLException or connection error points at the URI, while 404 responses point at path joining (the trailing-slash convention).

Note: this reflects well-established Gatling 3.x behavior; confirm against your exact Gatling version's documentation, as DSL details can change between minor releases.