CSV Data Set Config, Parameterization, Unique Data, and Test Data Strategy: Diagnostics, Failure Modes, and Production Practices

1. Preserve evidence before changing data

2. Diagnostic sequence

flowchart TD
E[Preserve JMX + CSV/hash + JTL + jmeter.log + target events] --> V[Confirm JMeter/Java/tool versions]
V --> C[Confirm exact CLI, target, file path, properties]
C --> D[Count rows + validate schema/duplicates/privacy]
D --> S[Map sharing mode to cursor domains]
S --> M[Compute row demand + EOF/recycle behavior]
M --> R[Inspect thread variables + request IDs]
R --> G[Inspect generator filesystem/CPU/GC]
G --> T[Inspect target collision/error evidence]
T --> X[Remote/CI/container file deployment if relevant]
X --> F[Least destructive correction]
F --> N[Small bounded rerun]

3. Failure mode: one account reused across threads

Symptom: 409/session invalidation or serialized behavior appears under concurrency. If Current thread sharing points every thread at the same accounts.csv, each private cursor starts at row 1.

Evidence: Debug Sampler shows identical ${user_id} values; server event log shows the same account claimed by thread 1 and thread 2. Repair the data mapping—not target locking or JVM heap.

4. Intentionally broken example: one-time data with Recycle=true

Three one-time tokens feed six iterations through an All-threads cursor. Recycle=true restarts after row 3, so tokens OT-1/2/3 are sent again. The fixture returns 409 reuse.

Repair options:

• provide at least six disjoint rows;
• reduce workload demand to three iterations; or
• set Recycle=false + Stop Thread=true when exhaustion should end activity.

Do not add retries. A retry would consume the same wrong/reused data policy again and distort the workload.

5. Failure mode: assuming remote engines receive the CSV automatically

The controller can access data/users.csv, but remote engine B logs a file-not-found error or reads a stale local copy. The JMX transfer/remote execution path does not provision arbitrary CSV data files.

Repair: deploy the exact shard to each authorized engine in the expected relative path, verify checksum/row count, then start the distributed run. Do not weaken RMI/TLS security to solve a filesystem problem.

6. Failure mode: every remote engine gets the same one-time file

Even if the file exists everywhere, uniqueness can still fail. Each remote process owns an independent All-threads cursor and starts at row 1. If every host has identical content, token 0001 can be consumed once per engine.

Repair with disjoint shards or a target-backed allocation service designed for concurrency. This chapter uses pre-shards because they are free, simple, and auditable.

7. Failure mode: real PII committed as fixture data

A developer copies customer email/name rows into data/users.csv and commits them. This is not merely a test failure; it is a data-protection incident depending on organizational policy/law.

8. Failure mode: relying on filesystem ordering for shard selection

A launcher lists shards/*.csv and assigns the first file to engine A, second to engine B. Another OS/filesystem returns entries in a different order, so engines receive swapped or duplicate data.

Repair with an explicit manifest keyed by engine identity. Verify path + SHA-256 before execution.

9. Failure mode: row count does not match demand

Two threads × five outer loops require ten rows in one All-threads one-time cursor, but the file has eight. Depending on settings:

• Recycle=true silently reuses two rows;
• Recycle=false/Stop=false emits <EOF> for later iterations;
• Recycle=false/Stop=true ends threads before the configured iteration count.

Configured load and achieved load are now different. Report the data-limited achieved sample count rather than claiming the target “couldn't handle” the planned iterations.

10. Failure mode: fewer CSV fields retain previous values

Current component documentation notes that if a row contains fewer values than configured variables, the remaining variables are not updated and can retain earlier values. A malformed row can therefore combine a new user ID with the previous iteration's other field.

Preflight CSV schema/column counts before load. Do not rely on the sampler to reveal malformed records at scale.

11. Failure mode: absolute paths work locally, fail in CI/remote

C:\Users\name\Desktop\users.csv or /home/me/users.csv couples the plan to one generator. Use a test-plan-relative path and ensure the file is packaged/mounted/deployed explicitly in each execution environment.

12. Causal performance separation

13. Shortcuts to reject

• Do not retry duplicate one-time data until it passes.
• Do not increase thread count when the dataset is already undersized.
• Do not increase heap before proving a generator memory problem.
• Do not copy the controller's real credentials/PII file to every remote engine.
• Do not disable TLS/RMI verification to solve missing CSV files.
• Do not replace explicit shard mapping with directory-order guesses.
• Do not delete failed JTL/jmeter.log/server evidence after repair.

Knowledge check

Official references and version notes

• Component Reference — CSV Data Set Config — row timing, headers, quoting, relative paths, EOF behavior, sharing modes, and per-thread file example.
• Remote (Distributed) Testing — remote engines execute the plan and have their own local runtime/filesystem state.
• Getting Started — GUI authoring/debugging and CLI execution conventions.
• Best Practices — generator validity, lean listeners, and pre-generated data guidance.
• Apache JMeter downloads — current production release and Java requirement.