PercentURL / application/x-www-form-urlencoded

What application/x-www-form-urlencoded Means in an HTTP Request

See where form fields go, how the request labels their format, and what to inspect when the server cannot read them.

It is related to URL query syntax, but a POST body is not the URL query string. The query belongs to the request URL; the form fields can instead travel in the request body.

See the request, not just the encoded text

Suppose a form submits two fields:

• email: [email protected]
• note: Tea & cake + coffee

A form-style serialization produces this body:

email=alex%40example.com&note=Tea+%26+cake+%2B+coffee

A POST request carries it separately from the path:

POST /submit HTTP/1.1
Host: api.example.test
Content-Type: application/x-www-form-urlencoded

email=alex%40example.com&note=Tea+%26+cake+%2B+coffee

Here, Content-Type labels the request body so the server can choose how to parse it. It is not the Accept header, which describes response formats the client can accept. The example serialization was cross-checked with Python's standard-library urllib.parse.urlencode().

An HTML form can select this format explicitly:

<form action="/submit" method="post"
      enctype="application/x-www-form-urlencoded">
  <input name="email" type="email">
  <textarea name="note"></textarea>
  <button type="submit">Send</button>
</form>

For HTML forms, this is the default enctype; the form's method is a separate choice. An omitted method defaults to GET, which places serialized fields in the action URL instead. For a POST form, the submitted field pairs go in the body. HTML Standard · MDN: Sending form data

Query string vs. form request body

A URL can still have its own query while a POST body is present. They are separate inputs; inspect and parse the one your endpoint expects. An encoder that transforms one parameter value does not build the whole HTTP request or configure the server's parser.

For a JavaScript request

When code submits the form with fetch(), the HTML form's enctype is not what serializes that manually built request. Create a URL-encoded body and inspect the fetch() options themselves:

const body = new URLSearchParams([
  ['email', '[email protected]'],
  ['note', 'Tea & cake + coffee'],
]);

fetch('/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body,
});

URLSearchParams serializes the pairs; this example sends them in the request body. If your Network panel instead shows JSON, a query string, or no body, check the code path actually used by the submit handler. MDN: Using the Fetch API

Debug in request order: body, fields, then parser

The browser can send a valid body while the route still sees no parsed fields. Check these items in order:

1. Confirm the request really has a body. In the browser Network panel, open the request and inspect Request Payload / Form Data. If the values appear after ? in the Request URL, the form used GET or the client placed them in the URL. 2. Read the exact Content-Type. For this parser, the request must use application/x-www-form-urlencoded (a supported charset parameter may also be present). A JSON body needs a JSON parser; a file-upload form uses multipart/form-data and a multipart parser. 3. Enable the matching parser before the route. Express does not populate req.body from a URL-encoded body until express.urlencoded() middleware has handled it. 4. Send fields in the format the header declares. Do not label a JSON object as URL-encoded data. Send a form-encoded string or let a form/query builder serialize the pairs. 5. Check the exact field names and repeated fields. The parser uses submitted names, not the label or element ID. Multiple controls can share a name; their parsed shape depends on parser configuration.

If one form field is missing

When the Network panel shows the request but a particular pair is absent from Form Data, stop changing URL encoding. First inspect the control in the submitted form. A control needs a non-empty name; an id is for identification and labels, and does not name the submitted pair. Disabled controls are omitted, and unchecked checkboxes and radio buttons are omitted too. A button contributes a value only when it is the button that submitted the form. These are browser form-submission rules, so a server-side parser cannot recover a pair that the browser never sent. HTML Standard: constructing the entry list

<!-- id alone: this value is not a submitted pair -->
<input id="email" value="[email protected]">

<!-- name supplies the key: email=alex%40example.com -->
<input id="email" name="email" value="[email protected]">

<!-- omitted while unchecked; included after it is checked -->
<input type="checkbox" name="updates" value="yes">

Use the visible Form Data list to compare expected and actual keys. If the pair is already present there but missing from req.body, move to the server side: confirm the route uses the matching parser, that the request Content-Type matches, and that middleware runs before the route. If the key exists but its value has the wrong shape, inspect repeated names and the parser option: Express documents that URL-encoded values can be strings or arrays with extended: false, while extended: true enables richer nested values. Don't assume every key is a single string. Express 5 API: express.urlencoded()

A control can also look like it belongs to a form while sitting outside that form in the document. If it must submit, associate it explicitly with the form's id using the control's form attribute; otherwise it is not part of that form's submitted entry list. This often appears after a page layout moves a field outside its original <form> element. HTML Standard: form control association

If the form has more than one submit button, test the exact button the user clicked. A submit button can override its form's action, method, and enctype through formaction, formmethod, and formenctype. One button can therefore send a POST body while another sends a GET query or selects a different encoding. Inspect the resulting Request URL, method, and Content-Type for each button; don't infer them from the parent <form> alone. HTML Standard: form submission attributes

If only large forms fail

When small submissions parse but a large form fails, inspect the parser's limits before changing serialization. Express documents a default URL-encoded body limit of 100kb and a parameterLimit of 1000; exceeding the parameter limit raises an error. Raise a limit only when the endpoint needs it, and keep a deliberate cap. Reproduce with the same request in Network, then compare its body size and number of pairs with the parser configuration. This separates an oversized request from a character-encoding problem. Express 5 API: parser options

Express example

import express from 'express';

const app = express();

// Register before routes that need form fields.
app.use(express.urlencoded({ extended: false }));

app.post('/submit', (req, res) => {
  res.json({ email: req.body.email, note: req.body.note });
});

If req.body is empty, check middleware order and the incoming Content-Type before changing the encoding. The official Express documentation describes express.urlencoded() as the middleware for these requests. Treat parsed values as untrusted input and validate them before use. Express 5 API: express.urlencoded

When this is the wrong format

• Uploading a file: choose multipart/form-data; URL-encoded form data is for text fields, not file bytes. MDN: <form> encoding types
• Sending a JSON API payload: send JSON and label it application/json; do not convert an entire JSON document into one URL-encoded field unless the API contract specifically calls for that.
• Encoding a value for a URL: encode the individual value for its destination context. Do not encode a complete URL and then place that result in a form body by mistake.

Form encoding only represents data; it does not encrypt it, validate it, or make a request private. Use HTTPS and the endpoint's documented authentication and validation rules.

Fast diagnostic checklist

• Request missing? Check that the form submitted and inspect its method and action.
• One key missing in Form Data? Check non-empty name, disabled, and checkbox/radio checked state.
• Body present but parser result missing? Match Content-Type to middleware and register it before the route.
• Repeated key or wrong value type? Check duplicate names and the parser's extended setting.
• Large form fails? Compare body size and pair count with parser limits.
• File selected? Use multipart handling rather than a URL-encoded text body.

Need to encode one URL value? Use the PercentURL URL encoder; for an actual form submission, let the form or HTTP client serialize the named fields and configure the matching body parser on the server.