In a JMeter distributed run, what does the controller actually send to each remote engine?

## What crosses the wire A distributed start is a small, fixed conversation. The controller clones the test tree, serialises it, and calls the remote engine's configure method with four things: **the test tree**, the host-and-port string the engine was addressed by, **the base directory expressed relative** to the JMeter working directory, and **the script's file name**. It then makes a second call to push the global property set. Finally it calls run. That is the entire payload. There is no file transfer channel in JMeter's remote protocol, no upload of a working directory, and no synchronisation step. The manual is explicit: the plan does not need copying, but *"if the test uses any data files, note that these are not sent across by the client so make sure that these are available in the appropriate directory on each server."* ## What must already be on the server | Artefact | Sent by the controller? | Where it has to be | |---|---|---| | The `.jmx` test plan | Yes, as a serialised tree | Nowhere - it arrives | | CSV data files | No | On every server, at the resolvable path | | Request body / upload files | No | On every server | | External script files a scripting element reads | No | On every server | | Keystores and certificates the plan opens | No | On every server | | Element and plugin classes | No | On every server's classpath | | The controller's own property files | No | Each server loads its own at startup | The last two rows cause the confusing failures. A third-party element that exists only on the controller cannot be deserialised on the server, so the run fails at configure time rather than with a helpful message about a missing plugin. That is the practical reason every node must run the same JMeter build and the same set of installed extensions. ## How the server resolves a relative path The relative base directory is the mechanism that makes relative filenames work at all. Suppose your plan lives in `<jmeter-home>/testplans/checkout/` and reads `data/users.csv`. The controller computes the base as `testplans/checkout` - relative, not absolute - and sends that. Each server sets its own file service base to that relative path, resolved against **its own** JMeter working directory. So if the server has the same directory layout, `data/users.csv` resolves; if its JMeter lives somewhere else on disk, it still resolves, because the path was never absolute. That design fails in exactly two ways, and both are common: - **An absolute path in the plan.** `/Users/you/work/users.csv` is taken as-is and will not exist on a Linux server. - **A different layout on the servers.** If the plan is in a directory the servers do not have, the relative base points at nothing and the file is not found. ## The failure it produces The plan runs clean locally and fails on the servers. Depending on which artefact is missing you get an error at configure time (a class that cannot be deserialised), an error as the engine starts the run (a data file that cannot be opened), or - worst of all - a run that completes on the wrong data, because the file was present but exhausted and the element handed every thread its end-of-file marker: with `Recycle on EOF` turned off and `Stop thread on EOF` left off, JMeter writes the literal `<EOF>` (the `csvdataset.eofstring` default) into each of the element's variables and the samplers keep firing. A file that is missing outright fails loudly instead - the file service throws `IllegalArgumentException: File users.csv must exist and be readable` the first time a thread opens the data set, and that thread dies. ## The habit that prevents it 1. Keep every file path in the plan **relative**, and keep the files under the plan's own directory. 2. Ship the whole plan directory - `.jmx` plus its `data/` and `scripts/` subdirectories - to the same relative location on every server, as one step of the deploy. 3. Install the same JMeter build and the same extensions on every node; do not hand-place a jar on one server only. 4. Run once against a single server before running against six. A missing file surfaces in seconds, not in the middle of a paid load window.