How to Use Headers in Middleware in Next.js

In Next.js middleware, you can access request headers using request.headers and modify response headers by returning a NextResponse with custom headers set via response.headers.set(). This lets you read, add, or change headers before the request reaches your pages or API routes.

Syntax

Next.js middleware runs before your routes and receives a Request object. You read headers from request.headers. To modify headers in the response, create a NextResponse and use response.headers.set(name, value) to add or change headers.

Return the NextResponse to continue the request with your header changes.

javascript

import { NextResponse } from 'next/server';

export function middleware(request) {
  // Read a header
  const userAgent = request.headers.get('user-agent');

  // Create a response
  const response = NextResponse.next();

  // Set a custom header
  response.headers.set('x-custom-header', 'my-value');

  return response;
}

Example

This example middleware reads the User-Agent header from the request and adds a custom header x-powered-by to the response. It then continues the request normally.

javascript

import { NextResponse } from 'next/server';

export function middleware(request) {
  const userAgent = request.headers.get('user-agent') || 'unknown';

  const response = NextResponse.next();

  response.headers.set('x-powered-by', 'Next.js Middleware');
  response.headers.set('x-user-agent', userAgent);

  return response;
}

Output

When a request is made, the response will include headers:
x-powered-by: Next.js Middleware
x-user-agent: (the user agent string from the request)

Common Pitfalls

• Trying to modify request.headers directly will not work because request headers are read-only.
• Always return a NextResponse object to apply header changes; returning nothing or the original request will ignore header modifications.
• Be careful not to overwrite important headers unintentionally.

javascript

import { NextResponse } from 'next/server';

// Wrong way: modifying request headers directly
export function middleware(request) {
  // This does nothing because request.headers is read-only
  // request.headers.set('x-test', 'value'); // ❌

  // Correct way:
  const response = NextResponse.next();
  response.headers.set('x-test', 'value'); // ✅
  return response;
}

Quick Reference

Action	Code Example
Read request header	const value = request.headers.get('header-name');
Create response	const response = NextResponse.next();
Set response header	response.headers.set('header-name', 'value');
Return response	return response;

Key Takeaways

Use request.headers.get() to read headers in Next.js middleware.

Modify response headers by creating a NextResponse and using response.headers.set().

Never try to change request.headers directly; they are read-only.

Always return a NextResponse to apply header changes.

Middleware runs before routes, so headers set here affect all downstream responses.