Where must a gatling.conf file sit for a Gatling run to pick it up, and what does the -Dgatling.conf.file system property actually change?

`gatling.conf` is the file where you override Gatling's defaults, and almost every problem people have with it comes from the same wrong assumption: that Gatling opens it as a file. It does not. It looks it up as a **ClassLoader resource**. ## The lookup, precisely Gatling's configuration loader reads two resources by name through the ClassLoader: `gatling-defaults.conf`, which ships inside the gatling-core jar and must not be edited, and `gatling.conf`, which is yours. Both are HOCON, parsed by the Typesafe Config library. The name of the second one — and only the name — can be changed with the system property `gatling.conf.file`. Values then resolve down a three-step fallback chain: **system properties > `gatling.conf` > `gatling-defaults.conf`** So `-Dgatling.core.shutdownTimeout=30000` on the command line beats the same key in your file, and your file beats the shipped defaults. Any key you do not set simply falls through to the defaults, which is why a `gatling.conf` holding three lines is perfectly normal. ## Where the file has to sit "On the classpath" is the rule; the directory that satisfies it depends on the build tool. | Build tool | Put `gatling.conf` in | Why | |---|---|---| | Maven | `src/test/resources` | the plugin always uses the project's test resources folder | | sbt | `src/test/resources` | Gatling simulations live in the `Gatling` configuration over `src/test` | | Gradle | `src/gatling/resources` | the plugin creates a `gatling` source set whose resources directory this is | | JavaScript / TypeScript | not applicable in the same way | the CLI has a `resources` folder, overridable with `--resources-folder` | A `gatling.conf` sitting at the project root, or next to the `pom.xml`, or in a `conf/` directory copied from the retired bundle layout, is invisible: none of those land on the run classpath. ## What `-Dgatling.conf.file` does and does not do It changes the **resource name** Gatling looks up. That is the whole of it. - `-Dgatling.conf.file=gatling-special.conf` works, provided `gatling-special.conf` is on the classpath — for a Maven project, that means it is in `src/test/resources`. - `-Dgatling.conf.file=src/test/resources/gatling-special.conf` does **not** work. It is still a resource lookup, and no resource is named that. This is the single most common mistake with the property, and Gatling's own documentation calls it out with exactly that pair of examples. ## The file's neighbours `gatling.conf` is not the only file that has to be in that directory. Gatling logs through Logback, so a custom `logback.xml` goes in the same resources folder — `src/gatling/resources` under Gradle, `src/test/resources` under Maven and sbt — and for the same reason: it is found as a classpath resource. The sbt plugin ships two convenience tasks for exactly this, `Gatling/copyConfigFiles`, which drops `gatling.conf` and `recorder.conf` into your project resources if they are missing, and `Gatling/copyLogbackXml`, which does the same for the default Logback configuration. ## Practical consequences 1. **A typo is silent.** If the resource is not found, the parse simply yields nothing and every key falls through to the defaults. Your run is not broken; it is just not configured. Gatling logs at INFO that it will try to load the file as a ClassLoader resource, which is the line to look for when a setting appears to be ignored. 2. **Comments are still comments.** The shipped file has every property commented out with a leading `#`. Editing the value without removing the `#` changes nothing. 3. **A system property always wins.** That makes system properties the right lever for per-run overrides in a pipeline and `gatling.conf` the right place for the project's standing choices. 4. **One name, several jars.** Because it is a classpath lookup, a `gatling.conf` inside a dependency jar is just as findable as yours. If two are on the classpath, which one wins is a classpath-order question you do not want to be having; keep exactly one. ## A worked example For a Maven project, create `src/test/resources/gatling.conf`: ```hocon gatling { core { encoding = "utf-8" shutdownTimeout = 30000 } } ``` Run `mvn gatling:test`; the file is on the test classpath, so it is found. To try an alternative without editing it, add `src/test/resources/gatling-tuning.conf` and run `mvn gatling:test -Dgatling.conf.file=gatling-tuning.conf` — name only, no path. And to override a single key for one run, skip the file entirely and pass `mvn gatling:test -Dgatling.core.shutdownTimeout=30000`, since system properties sit at the top of the fallback chain.