skip to content

In JMeter's HTTP Request, when is an uploaded file sent as the whole body rather than a multipart part?

level: middleimportance: should knowfreq 42%

answer

  1. The Parameter Name column decides everything
  2. One blank name, no parameters, raw body
  3. Mixing parameters and files drops one
  4. MIME Type becomes the request Content-Type

basics

~20 s

JMeter does that when the Files Upload tab holds one row with a blank Parameter Name and the Parameters tab is empty. The file's bytes become the body and the row's MIME Type becomes Content-Type.

solid answer

~40 s

The **Files Upload** tab has three columns — File Path, Parameter Name, MIME Type — saved as `HTTPsampler.Files`. A single row with a path and a **blank Parameter Name** is JMeter's signal to send the file as the entire request body, with the row's MIME Type becoming the `Content-Type` header unless a Header Manager already set one. Any row that carries a Parameter Name, more than one file, or a ticked **Use multipart/form-data**, produces a `multipart/form-data` body instead: one part per enabled parameter and one per file. The trap is the mixture: an unnamed file *plus* named parameters satisfies neither branch, so JMeter builds a plain form-encoded body and the file is never sent. **Browser-compatible headers** only affects the multipart branch, dropping the per-part `Content-Type` and `Content-Transfer-Encoding`.

code

xml · 9 lines
xml
<elementProp name="HTTPsampler.Files" elementType="HTTPFileArgs">
  <collectionProp name="HTTPFileArgs.files">
    <elementProp name="data/invoice.pdf" elementType="HTTPFileArg">
      <stringProp name="File.path">data/invoice.pdf</stringProp>
      <stringProp name="File.paramname"></stringProp>
      <stringProp name="File.mimetype">application/pdf</stringProp>
    </elementProp>
  </collectionProp>
</elementProp>

go deeper

for a junior

Know where the Files Upload tab is and what its three columns are called, and that leaving Parameter Name blank is meaningful rather than optional.

for a middle

State the branch rule from the table contents alone, and explain which field ends up as the request's Content-Type in each branch.

for a senior

Recognise the silent-drop combination in a plan review, and know that the file is re-read from disk on every execution rather than cached in the sampler.

for a principal

Decide how upload payloads are managed across a suite: where the fixture files live relative to the .jmx, how big they are allowed to be, and how a review catches a request that no longer carries its file.

The **Files Upload** tab of JMeter's HTTP Request sampler is a three-column table — **File Path**, **Parameter Name**, **MIME Type** — stored in the `.jmx` as `HTTPsampler.Files`. What JMeter builds out of it is decided entirely by the contents of that table plus the Parameters tab; there is no "send as body" switch. ## The rule JMeter asks two questions in order. 1. **Is this a single file with no parameter name?** That means exactly one row, a non-empty File Path, and an empty Parameter Name. If so, and the Parameters tab is empty, the file's bytes become the entire request body with no wrapper at all, and the row's MIME Type is used as the `Content-Type` header — unless an HTTP Header Manager already set one. 2. **Otherwise, is there at least one usable file row, or is Use multipart/form-data ticked?** Then JMeter builds a `multipart/form-data` body: one part per enabled request parameter and one part per file, each file part named by its Parameter Name and typed by its MIME Type. If neither holds, you get an ordinary `application/x-www-form-urlencoded` form built from the parameter table. ## The combination that silently loses your file The whole-body path also requires the **Parameters** tab to be empty. Put one named parameter beside a single unnamed file and JMeter takes neither branch: the file is not the body (parameters exist) and the request is not multipart (the file is still marked as a body candidate). It falls through to the plain form-encoded branch, whose code comments say outright that no file upload is allowed there. The request goes out with the parameters and **without the file**, and nothing in the sample marks it as wrong. The fix is to decide which shape you want: - give the file row a **Parameter Name** so it becomes a multipart part alongside the parameters; or - clear the Parameters tab so the file really is the body. ## Browser-compatible headers The **Browser-compatible headers** checkbox only matters in the multipart branch. Ticked, JMeter builds the entity in lax mode, which suppresses the `Content-Type` and `Content-Transfer-Encoding` headers on each part and leaves only `Content-Disposition`. Unticked, it uses RFC 6532 mode and encodes MIME header names and values as UTF-8. Reach for it when a server rejects JMeter's parts but accepts a real browser's. ## What each field controls | Field | Effect | |---|---| | **File Path** | Resolved through JMeter's FileServer: a relative path is tried against the working directory first and, failing that, against the base directory of the `.jmx`. | | **Parameter Name** | Empty on a lone file means "send as the body". Filled means "make it a multipart part with this name". | | **MIME Type** | The part's content type in multipart mode; the request's `Content-Type` in whole-body mode. Left blank, JMeter tries to guess it from the file. | | **Use multipart/form-data** | Forces multipart even with no files at all. | ## Practical notes - The file is read from disk on every execution, so a large upload is a per-request disk read on the load generator as well as a network cost. - The body JMeter records for the sample shows `<actual file content, not shown here>` in place of the bytes, so the results tree will not hand you back the uploaded file. - A file row whose File Path is empty makes JMeter log that the row is invalid and stops it counting as a usable file, which quietly changes which of the branches above you land in. For an interview, the sentence that shows you have actually done it is: *the Parameter Name column, not a checkbox, is what decides between a multipart part and a raw body — and if there are parameters as well, an unnamed file is dropped.*

  • What happens if you list one unnamed file and also fill in two named parameters?
    The file is dropped. The unnamed single file stops JMeter from choosing multipart, but the presence of parameters stops it from sending the file as the body, so it builds an ordinary form-encoded request from the parameters alone. The sample succeeds and gives no hint that the upload never happened.
  • What does the Browser-compatible headers checkbox change about a multipart request?
    It switches the multipart builder to lax mode, which suppresses the `Content-Type` and `Content-Transfer-Encoding` headers on each part so only `Content-Disposition` is emitted, and encodes MIME header values using the sampler's content encoding rather than UTF-8. It is there for servers that reject JMeter's stricter parts.

saying these in an interview costs you the question

  • Says a checkbox chooses between body and multipart
  • Thinks named parameters and an unnamed file both get sent
  • Believes MIME Type is only cosmetic
  • Assumes several files can share one empty parameter name
  • Expects the results tree to show the uploaded bytes