skip to content

Why does the file part vanish when a Postman script sends a form-data body with pm.sendRequest?

level: seniorimportance: nice to knowfreq 24%

answer

  1. A file part is a path, not bytes
  2. The sandbox has no filesystem to read
  3. Only the host process may open the file
  4. The call still goes, one part lighter
  5. Uploading files from scripts is not allowed

basics

~20 s

The sandbox strips file data out of a script-built request before dispatching it, reporting that uploading files from scripts is not allowed. The other parts go out normally, so the server sees a request missing exactly one part.

solid answer

~50 s

A file part in a Postman request is a **reference to a path**, not bytes carried in the document — the host process reads it off disk when the request is sent. Script code runs in a sandbox with no filesystem of its own: when a script builds a body containing a file part and passes it to `pm.sendRequest`, the sandbox removes the file data before the request crosses to the host, with the message that uploading files from scripts is not allowed. What makes it awkward to diagnose is that the call still goes out. The text fields arrive, the file part does not, and the server answers with a 400 that looks like its own problem. An upload that must really happen belongs in a stored request, where the host resolves the file.

code

javascript · 13 lines
javascript
pm.sendRequest({
    url: 'https://example.com/api/documents',
    method: 'POST',
    body: {
        mode: 'formdata',
        formdata: [
            { key: 'note', value: 'quarterly', type: 'text' },
            { key: 'doc', src: '/data/report.pdf', type: 'file' }
        ]
    }
}, function (err, res) {
    console.log(err, res && res.code);
});

go deeper

for a junior

Recall that a script cannot send a file. The file part of a body built in script code is removed before the request goes out, and the rest of the request is sent as normal.

for a middle

Explain the mechanism: a file part is a path resolved by the host at send time, and the sandbox has no filesystem, so file data is stripped from a script-built request before it crosses the bridge.

for a senior

Diagnose it from the outside. The visible failure is a server-side 400, so show how you distinguish a stripped part from a bad path, and where the upload belongs instead.

for a principal

Own the boundary argument: why script code is denied filesystem reach at all, and what it would cost in isolation and portability to relax it for convenience.

## The symptom A pre-request script builds a multipart body with a couple of text fields and one file part, passes it to `pm.sendRequest`, and the endpoint answers 400 — a missing-file complaint. Nothing in the script looks wrong. The path is right, the field name is right, the same upload works when it is sent as an ordinary request from the collection. The call is going out; it is going out incomplete. ## What the sandbox does Scripts run inside a sandbox: an isolated JavaScript context with **no filesystem and no network stack of its own**. When a script calls `pm.sendRequest`, the request object is serialised and handed across a bridge to the host runtime, which performs the exchange. A file part is not data. In a Postman request, a file is a **reference to a path** — the bytes stay on disk and the host reads them at send time. That is the collision: - The script has a path but cannot read it. - The host can read it but was not asked to by an item of the collection. - Allowing the bridge to carry a path would hand arbitrary script code the ability to read any file the host process can reach. So the sandbox resolves it by **stripping the file data out of a script-built request** before dispatch, and says so: uploading files from scripts is not allowed. The rest of the request is untouched. ## Why this is hard to see | What you expect | What happens | |---|---| | The call is refused outright | The call goes out, minus one part | | The error names the client | The error comes from the server, as a 400 | | The file is somewhere in the payload | The file part was removed before the send | | The path was wrong | The path was never read at all | The failure looks like a server problem because the only visible artefact is the server's answer. A quick way to confirm the diagnosis is to inspect what actually left: log the fields the endpoint reports receiving, and you will find the text parts present and precisely the file part absent — a pattern no path typo produces. ## The reasoning behind the rule Three things are being protected at once: 1. **Isolation.** The sandbox's value is that script code cannot reach the machine it runs on. A file-by-path upload from a script would be a hole straight through that boundary. 2. **Portability.** A collection is a document meant to travel. A script that reads local paths behaves differently on every machine that runs it, and fails on every machine that does not have the file. 3. **Consistency of the document.** When an upload is a stored request, the file reference is part of the collection and visible to anyone reading it. When it is assembled in script code at run time, it is visible only to whoever reads the code. ## What to do instead - **Make the upload a stored request.** A request that the run executes has its file reference resolved by the host, which is the only component that can legitimately read the disk. - **Keep the script for the parts that need no file.** Fetching a value, checking a precondition, or shaping a field is exactly what a side call is good at. - **Do not try to smuggle the bytes.** Reconstructing the file in script code is not a workaround so much as a way to hide a large blob inside a collection and defeat the reason the restriction exists. - **Watch for it after a refactor.** The common origin of this bug is an upload that used to be a stored request being folded into a helper script, where it silently stops carrying its file. - **Assert on what came back.** A side call whose result nobody looks at will hide this failure indefinitely, since the strip itself produces no visible interruption in the run. ## The takeaway The rule is narrow and absolute: `pm.sendRequest` sends a request the script built, and a script may not send files. Everything else about the request goes through, which is what makes it a diagnosis worth having ready — the wrong instinct is to hunt for a broken path or a mis-set content type, when the correct model is that the part was removed on purpose, at the boundary, before the request ever reached the network.

  • Why is this a boundary decision rather than a missing feature?
    Because a file part names a path and only the host process can read it. Letting script code post arbitrary paths across the bridge would let a collection exfiltrate any file the host can open, and would make the collection's behaviour depend on the machine running it. Stripping keeps the sandbox isolated and the document portable.
  • How would you confirm this is what happened rather than a bad path?
    Look at what the endpoint says it received. A stripped file yields the text parts present and exactly the file part missing, with no client-side interruption in the run. A bad path fails differently, and the same upload sent as a stored request succeeds — which isolates the script boundary as the cause.

saying these in an interview costs you the question

  • Blames a mistyped path instead of the sandbox boundary
  • Expects the call to be refused rather than silently trimmed
  • Thinks an absolute path makes the file readable from a script
  • Believes the file is inlined into the collection document
  • Proposes reconstructing the bytes in script code as a fix