A config element that adds headers to the HTTP requests in its reach.

JMeter test plans are built from samplers that send requests, controllers that decide the flow, timers that add pauses, assertions that check responses and config elements that provide shared settings. The HTTP Header Manager is a config element. It holds a simple table of header names and header values, and it attaches those headers to the HTTP requests that fall inside its scope. It sends no request on its own and it creates no sample in the results.

Its purpose is to make the requests look like the requests that real clients send. A browser, a mobile application or another service always adds a collection of headers automatically. A load test client such as JMeter adds only a small basic set by itself, so anything beyond that must be supplied deliberately. The Header Manager is the tidy place to supply it.

What it is not

It is not a place to decide the target host, because the HTTP Request Defaults element handles that. It is not the right place for cookies, which have their own manager. It is not a security feature, a validator or a transformer of response data. It simply attaches request headers, and because those headers can change how the server behaves, a wrong value can silently change what a whole test measures.

Before configuring headers, learn what they are and why servers care.

Every web request has three parts: a first line saying what is wanted, a block of headers giving extra information and an optional body carrying data. A header is a simple pair made of a name and a value, such as a name meaning the format of the data and a value naming that format. Headers are small, but servers, gateways, caches and security tools read them constantly to decide how to treat each request.

Headers fall into groups by purpose. Some describe the body, such as its format and size. Some describe what the client can accept in return, such as formats, languages and compression. Some carry identity and permission, such as tokens and keys. Some describe the client itself, such as the browser or application name. Others are custom, invented by an application for its own needs, such as a request identifier used for tracing.

Header names are not case sensitive in the standard, and newer versions of the protocol send them in lower case. Values, however, are often case sensitive in practice, especially tokens. Spelling, spacing and punctuation in values matter, so copying them exactly from a real client is a safe habit.

Missing or wrong headers produce fast, cheap, misleading results.

A load test is only useful if the server does real work for each request. Headers decide whether it does. A request without a valid token is usually rejected by a gateway within a few milliseconds, long before any business logic or database access happens. A test full of such requests will show beautiful response times and a flat, healthy server, while telling you absolutely nothing about real capacity.

Headers also change which code path runs. A request that says it wants one format may trigger different serialisation work from one that asks for another. A request that states a mobile client may receive a lighter version of a page. A request that says it accepts compression forces the server to spend processor time compressing responses. Every one of these differences changes the load that the test applies.

A name, a value and a few helper buttons make up the whole dialog.

The Header Manager dialog is a table with two columns: the header name and the header value. Each row is one header that will be added to requests in scope. Buttons beneath the table let you add a row, add several rows pasted from the clipboard, delete rows, load a saved set of headers from a file and save the current set to a file. Learning these helpers early saves a lot of retyping.

Values can be dynamic

A header value does not have to be fixed text. It can contain variables and functions, which JMeter resolves at the moment the request is sent. This is how a token captured from a login response becomes the authorisation header for every later request, and how each virtual user can send its own identifier. Dynamic values are the feature that turns the manager from a static label printer into a realistic client simulator.

Where you place the manager decides which requests receive its headers.

A JMeter plan is a tree, and config elements follow scoping rules based on position. A Header Manager placed under the test plan reaches the samplers of every thread group. One placed under a thread group reaches only that group. One placed under a controller reaches only the samplers inside that controller. One placed directly under a single sampler reaches only that request. The closer the manager is to the request, the narrower its reach.

flowchart TD
    TP["Test Plan"] --> H0["Header Manager: global headers"]
    TP --> TG["Thread Group"]
    TG --> SC["Simple Controller: JSON API calls"]
    SC --> H1["Header Manager: JSON content type"]
    SC --> S1["Sampler: create order"]
    SC --> S2["Sampler: update order"]
    TG --> S3["Sampler: download page"]
    S3 --> H2["Header Manager: one-off header"]
        

Merging when several managers apply

When more than one Header Manager applies to a request, JMeter combines them, so the request carries the headers from all of them. Where two managers define the same header name, only one value can be sent, and the manager nearer to the request generally takes priority. Because precedence between managers at the same level is hard to reason about, the safest design is to avoid defining the same header name in more than one place, and to confirm the final headers in the results viewer.

The two most important headers for API testing describe the format going out and coming back.

The content type header tells the server how to read the body of the request. When a request carries a body in a structured format such as JSON or XML, the server needs this header to know how to parse it. If the header is missing or wrong, the server may reject the body, treat it as plain text or fall into an error path. These error paths are usually very fast, which makes the test look excellent while the real parsing and business work never happens.

JMeter sets the content type automatically for ordinary form submissions built from parameters, but when you supply a raw body, you must provide the matching content type yourself. The accept header does the reverse job: it tells the server which formats you can read in response. Some services return different formats depending on this header, and some refuse the request if no acceptable format can be produced.

Where to put them

A neat pattern is to group all requests that share a format under one controller and attach a Header Manager to that controller. Every JSON request then inherits the correct headers, and requests of other kinds, such as form submissions or file uploads, remain untouched in other branches. This avoids the common error of forcing a JSON content type onto a request that actually carries form data.

Modern APIs identify callers through tokens carried in headers.

Most modern services use tokens instead of sending a username and password every time. A caller logs in once, receives a token, and then attaches that token to every later request inside a header. The server checks the token, identifies the caller and decides what the caller may do. Reproducing this flow in a load test means capturing the token from the login response and placing it in the header of subsequent requests, separately for each virtual user.

sequenceDiagram
    participant U as Virtual User
    participant L as Login Request
    participant E as Extractor
    participant H as Header Manager
    participant A as Protected Request
    participant S as Server
    U->>L: Send credentials
    L->>S: Login call
    S-->>L: Response with token
    L->>E: Pass response
    E->>E: Store token in a variable
    U->>A: Next protected call
    H->>A: Insert token into authorisation header
    A->>S: Request with token
    S-->>A: Real business response
        

Making it work per user

The header value refers to a variable that holds the token. Because variables belong to each virtual user, every user sends their own token, exactly as real users do. The login request and its extractor must run before the first protected request, or the variable will be empty and the header will carry nothing useful. Controllers such as Once Only are commonly used to keep login at the start of each user’s visit.

Describing the client correctly changes what the server sends back.

The user agent header names the client software. Servers use it to decide which version of a page to send, whether to apply device-specific features and sometimes whether to treat the caller as an automated tool. A test client that announces itself with its default identity may be treated differently by security tools and content delivery systems, which can skew results in either direction.

The language header influences which translated content the server returns, and in some systems it triggers different database queries and different template sets. A test sending only one language can therefore miss performance problems that appear in another language. Representing the real mix of languages among your users makes the load more realistic.

flowchart LR
    R["Request with client headers"] --> D{"Server reads User-Agent and Language"}
    D -- "Desktop client" --> P1["Full desktop page"]
    D -- "Mobile client" --> P2["Lighter mobile page"]
    D -- "Different language" --> P3["Translated content and extra queries"]
    D -- "Known automation tool" --> P4["Possible blocking or throttling"]
        

Modelling a mix of devices

If analytics show that sixty percent of visitors use mobile devices, a single desktop identity underrepresents the lighter pages and overrepresents the heavier ones. A good design creates separate journeys, each with a Header Manager describing one device type, and sizes the thread groups in proportion to the real traffic mix. This keeps each journey simple and makes the proportions easy to change.

Some headers control how much data travels and whether work can be skipped.

Compression headers tell the server which methods the client can decode. When a client announces support for compression, the server may compress responses, spending processor time to save network bandwidth. Real browsers almost always announce support, so a test that omits it sends heavier responses and spends less server processor time than reality. The reverse is true when the client announces support: the transferred size falls while server work rises.

Caching headers and conditional request headers let a client ask, “send me this only if it has changed since I last got it.” The server can answer with a tiny message saying nothing changed, avoiding the cost of sending the full content again. Real browsers do this constantly for images and scripts. A test that never sends such headers makes the server resend everything every time, exaggerating static content load.

Let the right element do the caching

For browser-like caching behaviour, JMeter has a dedicated cache manager element that handles these conditional headers automatically. Typing conditional headers by hand into a Header Manager is fragile and rarely realistic. Use the Header Manager for fixed declarations and the cache manager for the dynamic caching conversation.

Headers can carry labels that help you follow a single request through a whole system.

In distributed systems, one user request may pass through a gateway, several services and a database. When something is slow, finding which request and which service caused it is hard. Many systems solve this by passing a request identifier or trace identifier in a header, which every service logs. If the load test sets its own identifier per request, engineers can search the logs and find the exact path of any slow sample.

Useful custom headers in testing

Some headers have a better owner than the Header Manager.

JMeter and its companion elements already look after several headers. Cookies are handled by the cookie manager, which stores the cookies each virtual user receives and sends them back at the right times. The body length header is computed from the actual body, so typing a fixed value there is dangerous. Connection handling headers depend on how the underlying client reuses connections. Interfering with these by hand usually causes subtle failures.

Static labels are easy; realistic labels change per user and per request.

A header value may refer to variables, properties and functions, which JMeter resolves when the request is sent. Variables carry per-user data, such as a token captured at login or an identifier read from a data file. Properties carry settings for the whole run, such as an API key or a version label supplied when the tool is launched. Functions produce values such as counters, time stamps and random numbers, useful for unique identifiers.

Timing and ordering

A dynamic header value is resolved when the request is about to be sent, so the variable it refers to must already hold a value by then. If an extractor runs after the request that needs its output, the header carries an empty or placeholder value. Always check the order of requests and extractors, and run a single-user rehearsal to confirm that the first protected request already carries the right value.

A few simple placement rules keep plans readable and headers predictable.

Header Managers are easy to add and just as easy to scatter. A plan with a dozen managers in random places becomes hard to understand. A small set of placement rules keeps things tidy. Put headers that every request needs at the top. Put headers that belong to a group of requests on the controller that groups them. Put headers that belong to one request on that request, and only when truly necessary.

flowchart TD
    A["New header to add"] --> B{"Needed by every request?"}
    B -- "Yes" --> C["Place at plan level"]
    B -- "No" --> D{"Needed by a group of requests?"}
    D -- "Yes" --> E["Place on the controller that groups them"]
    D -- "No" --> F["Place on the single request"]
    C --> G["Verify final headers in results viewer"]
    E --> G
    F --> G
        

Sharing header sets

The load and save buttons let a team keep a standard header set in a shared file. For larger plans, a Test Fragment can hold a Header Manager together with related elements, and journeys that need it include the fragment through a module controller. This keeps the standard definitions in one place, so a change to a common header is made once and applies everywhere it is used.

Recorded headers include a lot of noise that should be removed before reuse.

The HTTP test script recorder captures what a real browser sent, including every header. The recorded output is a useful starting point, but it carries items that do not belong in a repeatable test. It may contain cookies, body lengths, a fixed host header, connection instructions and tokens that expire quickly. Leaving these in produces a script that works once and then fails, or that behaves unnaturally for every virtual user.

flowchart TD
    A["Record browser session"] --> B["Recorder creates header managers"]
    B --> C["Remove cookie, length and connection headers"]
    C --> D["Replace expiring tokens with extracted variables"]
    D --> E["Keep stable headers such as accepted formats and client name"]
    E --> F["Merge duplicates into plan or controller level"]
    F --> G["Rehearse with one user and inspect headers"]
        

Why recorded headers repeat

Recorders often create a header manager near each request, because they capture request by request. The result is many managers with near-identical contents. Merging them into one at a higher level reduces clutter, and it removes the risk of the same header with different values in different places, which was described earlier as a source of unpredictable behaviour.

The Header Manager is one member of a small team of config elements.

Each config element owns a concern. Keeping those concerns separate makes plans easier to understand and prevents the temptation to stuff everything into one place. The table below shows the usual division of labour.

Never assume the headers you configured are the headers that were sent.

Because several managers can apply and because dynamic values depend on timing, the only safe approach is to inspect the real request. The results viewer shows, for each sample, the exact headers that went out and the exact response that came back. A single-user rehearsal of a few iterations, with the viewer open, answers most header questions within minutes.

Symptoms and likely causes

Headers change what the numbers mean and how much each request costs.

Headers influence measured results in three ways. They change the server’s behaviour, as when a missing token causes early rejection. They change the size of the traffic, as when compression or large tokens alter the bytes sent and received. They change the work on the injector, as when decoding compressed responses uses processor time on the load generator. Each effect is real, so headers must be part of the test design, not an afterthought.

The size of the headers themselves

Individual headers are small, but tokens can be long, and some systems also attach many cookies and custom headers. When thousands of requests per second each carry a large header block, the combined bandwidth and parsing cost become visible. Real clients carry the same weight, so matching their header size is part of realism. Stripping headers to make tests lighter produces results better than reality.

Keeping runs comparable

For fair comparisons between builds or environments, freeze the header design and record it with the results. If a header changes between runs, treat the runs as different experiments. The most trusted performance reports state which headers were used, especially compression, client identity and authorisation style.

Headers often carry the most sensitive values in the whole test plan.

Tokens, keys and credentials usually travel in headers, which means a Header Manager can hold some of the most valuable secrets in the test. Plan files are shared, stored in repositories and attached to tickets. A token typed directly into a manager can end up in places it should never be. Careful handling of these values is a basic part of professional testing.

When many machines or pipelines run the plan, header values must be consistent.

In a distributed test, a controller machine sends the plan to several injectors, and each runs it independently. Header values typed into the plan travel with it. Values supplied as properties, however, must exist on every injector, or an injector may fall back to a different default, quietly sending the wrong key or version label. Differences like this are hard to spot because the test still runs.

Habits that keep headers helpful instead of hazardous.

The same element solves very different problems.

It attaches a table of header names and values to the HTTP requests in its scope, so requests carry the labels that real clients send, such as formats, tokens and client identity.

Place universal headers at plan level, group headers on the controller that groups the requests, and rare exceptions on a single request. Avoid defining the same header name in several places.

Their headers are combined. If the same name appears in more than one, the nearer manager generally takes priority, but verify the final request in the results viewer instead of relying on assumptions.

No. JMeter sets it for form submissions built from parameters. You must supply it yourself for raw bodies such as JSON or XML, and it is best attached at the controller that groups those requests.

Extract the token into a variable with a post-processor on the login request, then refer to that variable in the authorisation header value of a Header Manager covering the later requests.

No. Use a cookie manager, which gives each virtual user their own session and updates cookies automatically as responses arrive.

Requests may be rejected early because of missing or invalid headers such as tokens or content types. Inspect response bodies and add assertions for genuine business content.

Avoid it. Supply short-lived test tokens at run time through protected properties, and keep plans and result files free of real credentials.

Yes. Use variables fed by extractors or data files, or functions that generate unique values, so each user sends their own value at the moment of the request.

Run a single user and inspect the requests in the results viewer, which shows the exact headers sent and the response received for each sample.

The defaults element decides where requests go and shared client settings such as timeouts. The Header Manager attaches labels to the messages themselves. Each has its own job.

Yes. Remove cookies, body lengths and connection headers, replace expiring tokens with extracted variables, and merge duplicate managers into one at a sensible level.

The HTTP Header Manager looks like a plain two-column table, yet it decides whether your virtual users look like real clients or like confused strangers. Correct headers keep the server doing genuine work, route requests down realistic code paths, carry the identity of each user and make traffic traceable. Wrong or missing headers produce fast, flattering, meaningless results. Treat the header design as a deliberate, documented, secured and verified part of every test plan.