A JMeter plan using a jp@gc element runs locally but dies on a clean CI checkout before any sample. Why?

This is the failure that turns a plugin into an operational problem rather than an authoring convenience, and it is worth being able to describe from both ends: what the log says, and what you change so it stops happening. ## What the failure actually is A JMeter test plan is XML in which every element is recorded by its Java class. Core elements resolve to `org.apache.jmeter.*` classes that are always present; a third-party element resolves to the plugin's own class, and jp@gc plugins publish theirs - the Dummy Sampler's marker class is `kg.apc.jmeter.samplers.DummySampler`, for instance. Nothing in the file says where the jar came from or which version it was. When JMeter reads the plan it hands the XML to its object mapper. If a class in the file is not on the classpath the mapper cannot resolve it, and `SaveService` deliberately turns that into a hard failure: it catches the resolution error and rethrows an `IllegalArgumentException` reading `Problem loading XML from:'<absolute path>'` with the root cause attached. In non-GUI mode that surfaces as `Error in NonGUIDriver`, the top-level handler prints `An error occurred: ...` and calls `System.exit(1)`. So the shape of the failure is: - it happens **at load**, before the test tree is compiled and before any thread starts; - the process exits **non-zero**, and the message names the file it could not load; - **no JTL is produced** at all, so there is not even a partial results file to inspect. ## The other shape: a missing class that does not stop the run Not every missing class behaves this way, and knowing the difference saves an hour of debugging. A Java Request sampler stores its target class as a *string field*, not as the element's own class. If that class is absent, the plan still loads; the sampler substitutes an internal error client, and every sample comes back failed, labelled `ERROR: <classname>`, with response data `Class not found: <classname>`. That run produces a full JTL of failures at whatever rate the thread group asked for. So: **a missing plugin element makes the plan unloadable; a missing JavaSamplerClient makes the samples fail.** One is a red build in five seconds, the other is a red build in fifteen minutes. ## Making the plugin survive a clean checkout The plan cannot carry the plugin, so the environment must. Three approaches, roughly in order of how much a team tends to like them once they have lived with them: 1. **Bake it into the runner image.** The Dockerfile or the AMI copies the pinned plugin jars into `lib/ext` and their dependencies into `lib`. Reproducible, offline, and the image tag records the plugin set. 2. **Vendor the jars into the repository** beside the plan and point `search_paths` (for plugin jars) and `plugin_dependency_paths` (for their dependencies) at the checked-out directory. The plan and its plugins move together, at the cost of binaries in git. 3. **Install at the start of the job with the Plugins Manager's command line.** The Plugins Manager is a third-party tool from JMeter-Plugins.org, not part of the Apache download. Put its jar in `lib/ext`, make sure a `cmdrunner` jar is in `lib`, and generate the wrapper scripts by running its `PluginManagerCMDInstaller` class; `PluginsManagerCMD` then takes `status`, `available`, `upgrades`, `install`, `install-all-except`, `install-for-jmx` and `uninstall`. `install-for-jmx` reads a `.jmx` and installs what that plan needs, which is convenient but resolves versions at job time; `install jpgc-dummy=0.4` pins one instead. ## The rules that keep it fixed - **Pin the version.** A plugin id without a version installs whatever the repository offers today, which makes yesterday's green build unreproducible. - **Do not rely on network access at run time.** An install step that reaches a public repository turns an outage into a red build; the Plugins Manager can be pointed at an internal mirror through its `jpgc.repo.address` property if you want the convenience without the dependency. - **Fail loudly at provisioning time.** Verifying the jars exist before invoking JMeter turns an obscure XML error into a clear message. - **Vet what you install.** Licence and supply-chain review of a third-party jar is a real obligation and belongs with your application-security practice, not with the test plan. - **Watch the coupling.** A plugin binds to JMeter's internals, so a JMeter upgrade can outrun a plugin that has not been rebuilt for it. Upgrade both together and keep the previous image tag until the new one has been through a run.