IPGeolocation.io Next.js Middleware for Vercel

1. Step 1. Add your API key

Create .env.local in your project root:

IPGEOLOCATION_API_KEY=your_api_key_here

Add the same variable in your Vercel project under Settings > Environment Variables for Production, Preview and Development.

2. Step 2. Create the middleware file

On Next.js 13, 14 and 15, create middleware.ts in your project root, next to app/ or pages/ :

import { middleware } from 'ipgeolocation-vercel-middleware/middleware';

export { middleware };

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|_next/data|favicon.ico|robots.txt|sitemap.xml|.*\\.(?:css|js|mjs|map|json|txt|xml|ico|png|jpg|jpeg|gif|webp|avif|svg|woff|woff2|ttf|otf|eot|mp4|webm|mp3|pdf|zip)$).*)'
  ]
};

On Next.js 16, the file is named proxy.ts and the exported function is named proxy :

import { proxy } from 'ipgeolocation-vercel-middleware/middleware';

export { proxy };

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
};

Declare config in your own file rather than re-exporting it from the package. Next.js reads the matcher statically at build time and cannot follow a value that comes from a dependency. Next.js 16 rejects a re-exported config outright.

The matcher above skips Next.js internals and files with a static extension. Every path you exclude is a lookup you do not pay for.

3. Step 3. Add a block page

Only needed if you use country or security rules with the default block mode. Create app/blocked/page.tsx :

export const metadata = {
  title: 'Access restricted',
  robots: { index: false, follow: false }
};

export default async function BlockedPage({
  searchParams
}: {
  searchParams: Promise<{ reason?: string }>;
}) {
  const { reason } = await searchParams;

  return (
    <main>
      <h1>Access restricted</h1>
      <p>We could not accept this connection ({reason ?? 'policy'}).</p>
      <p>
        If you think this is a mistake, contact{' '}
        <a href="mailto:support@example.com">support@example.com</a>.
      </p>
    </main>
  );
}

On Next.js 13 and 14, searchParams is a plain object rather than a promise, so drop the await and the Promise type. A fuller example with a message for every reason is in examples/app/blocked/page.tsx.

If you would rather not create a page at all, set IPGEO_BLOCK_MODE=deny and the middleware answers with a plain HTTP 403.

4. Step 4. Switch on the rules you want

Everything is configured through environment variables. A few common starting points:

# Geolocation headers only, no blocking. Costs 1 credit per uncached lookup.
IPGEOLOCATION_API_KEY=your_api_key_here

# Serve three countries and nobody else.
IPGEOLOCATION_API_KEY=your_api_key_here
IPGEO_ALLOWED_COUNTRIES=US,CA,GB

# Send visitors to locale paths.
IPGEOLOCATION_API_KEY=your_api_key_here
IPGEO_COUNTRY_REDIRECTS={"US":"/us","GB":"/uk","DE":"/de"}

# Block anonymised and high risk traffic. Needs a paid plan.
IPGEOLOCATION_API_KEY=your_api_key_here
IPGEO_BLOCK_VPN=true
IPGEO_BLOCK_TOR=true
IPGEO_THREAT_SCORE_BLOCK_THRESHOLD=75

5. Step 5. Read the data in your application

// app/page.tsx
import { headers } from 'next/headers';

export default async function Page() {
  const h = await headers();
  const country = h.get('x-ipgeo-country');
  const city = h.get('x-ipgeo-city');

  return <p>Hello from {city ?? 'somewhere'}, {country ?? 'unknown'}</p>;
}

On Next.js 13 and 14, headers() is synchronous, so drop the await .

6. Step 6. Check that it works

Run next dev and open the site. Locally there is no edge network in front of you, so the request arrives from 127.0.0.1 , which the API cannot resolve. The middleware recognises a private address and passes the request through without spending a credit, which means no headers are set. To see real data locally, send a public address yourself:

curl -H 'x-forwarded-for: 91.128.103.196' http://localhost:3000/

Set IPGEO_LOG_LEVEL=debug while you are setting things up and the middleware reports each lookup, each cache hit and the credits charged. Move back to the default warn afterwards.

1. Block modes

redirect sends a 307 to IPGEO_BLOCK_PATH with the reason as a query parameter. The visitor sees the block URL in the address bar, and your block page can explain what happened. This is the default.

rewrite renders the block page at the URL the visitor asked for. The status stays 200 and the URL does not change, which suits cases where you would rather not advertise that a rule fired.

deny answers immediately with IPGEO_BLOCK_STATUS and IPGEO_BLOCK_MESSAGE as plain text. No page is needed, nothing else runs, and there is no way to create a loop. This is the right mode for an API only deployment.

Every block response carries x-ipgeo-block-reason and cache-control: no-store , so a shared cache cannot serve one visitor's decision to another.

2. Block reasons

The reason appears in the reason query parameter and in the x-ipgeo-block-reason header.

3. Fail open and fail closed

By default a failed lookup lets the request through. An API incident, a timeout or an exhausted quota then costs you enforcement rather than availability. Set IPGEO_FAIL_CLOSED=true when the rules matter more than uptime, for example on a licensing or compliance boundary.

A private or malformed address is not treated as a failure. Those requests pass through even in fail closed mode, because blocking them would break local development and internal health checks.

1. No x-ipgeo-* headers reach my application

Cause: the middleware never ran, the lookup never happened, or the headers were dropped downstream.

Fix: work through these in order.

1. Confirm the file is at the project root next to app/ or pages/ , not inside app/ . Next.js 16 expects proxy.ts rather than middleware.ts .
2. Confirm the request path matches the matcher. A path excluded by the matcher never reaches the middleware.
3. Confirm IPGEOLOCATION_API_KEY is set in the environment you are testing. Without a key the middleware passes every request through in silence.
4. Set IPGEO_LOG_LEVEL=debug and look at the runtime logs for the lookup line.
5. If you wrote your own middleware around this one, make sure you return NextResponse.next({ request: { headers: geo.requestHeaders } }) . A bare NextResponse.next() discards them.

2. Build fails with It mustn't be reexported

Cause: config was re-exported from the package, as in export { middleware, config } from 'ipgeolocation-vercel-middleware/middleware' . Next.js reads the matcher statically at build time and cannot resolve a value that lives in a dependency.

Fix: re-export only the function and declare config in your own file:

import { middleware } from 'ipgeolocation-vercel-middleware/middleware';

export { middleware };

export const config = { matcher: ['/((?!_next/static|_next/image).*)'] };

3. TypeScript cannot find ipgeolocation-vercel-middleware/middleware

Cause: moduleResolution is set to node , which predates package export maps and cannot see subpath exports.

Fix: set "moduleResolution": "bundler" in tsconfig.json , which is what create-next-app generates. node16 and nodenext also work.

4. Security rules do nothing, and the logs mention HTTP 401

Cause: the security module needs a paid plan. A free key that asks for it receives HTTP 401.

Fix: upgrade at ipgeolocation.io/pricing, or switch the security rules off and use country rules instead. The middleware retries the lookup without the module so your site keeps working, and it stops asking for five minutes rather than repeating the error on every request. While the module is unavailable, no VPN, proxy, Tor, bot, spam, attacker or threat score rule can fire. Set IPGEO_REQUIRE_SECURITY=true if you would rather block traffic than let it through unverified.

5. Everything is blocked after I switched on fail closed

Cause: in fail closed mode any failed lookup becomes a block. An invalid key, an exhausted quota or a network problem takes the whole site down.

Fix: check the logs for the failure reason. unauthorized points at the key or the subscription, rate_limited at the daily quota, timeout at network conditions. Verify the key directly:

curl "https://api.ipgeolocation.io/v3/ipgeo?apiKey=YOUR_KEY&ip=8.8.8.8"

While you investigate, set IPGEO_FAIL_CLOSED=false or IPGEO_ENABLED=false .

6. Redirect loop after setting up country redirects

Cause: in 1.x a target with a trailing slash, such as {"GB":"/uk/"} , redirected forever. It can also happen when the target path does not exist and your application rewrites it back.

Fix: upgrade to 2.0.0, which normalises the target and leaves a visitor alone once they are at or below it. Then confirm the target path really exists, and that no next.config.js rewrite sends it back to the root.

7. Locally I get no data, or the logs mention a private address

Cause: in next dev there is no edge network in front of you, so the request comes from 127.0.0.1 . The API answers HTTP 423 for private and bogon ranges, so the middleware skips the lookup.

Fix: send a public address yourself while testing:

curl -H 'x-forwarded-for: 91.128.103.196' http://localhost:3000/

8. Credit usage is higher than expected

Cause: the matcher is too broad, the cache window is too short, or the security module is being requested when you do not need it.

Fix: exclude static files and Next.js internals from the matcher, as in the Quick Start. Raise IPGEO_CACHE_TTL_MS . Switch off any security rule you are not using, which takes an uncached lookup from 3 credits back to 1. Set IPGEO_LOG_LEVEL=debug to see the credits charged per lookup, and check your usage in the dashboard.

9. The wrong country is detected, or every visitor looks the same

Cause: the address being looked up is a proxy rather than the visitor.

Fix: log x-ipgeo-ip and compare it with the visitor's real address. If it belongs to your own infrastructure, set IPGEO_TRUSTED_PROXY_COUNT to the number of proxies you run in front of the application. On Vercel without a custom proxy, leave both IPGEO_TRUST_FIRST_XFF and IPGEO_TRUSTED_PROXY_COUNT at their defaults.

10. Search engines stopped indexing the site

Cause: a crawler was blocked. Country rules and IPGEO_BLOCK_CLOUD_PROVIDER both catch crawlers, since they run from datacenter ranges.

Fix: keep IPGEO_ALLOW_KNOWN_GOOD_BOTS=true , which is the default, so crawlers the API marks as known good survive IPGEO_BLOCK_BOT . Be careful with IPGEO_BLOCK_CLOUD_PROVIDER , which does not make that distinction. Make sure your block page sends noindex , and exclude robots.txt and sitemap.xml from the matcher.

11. Health checks and webhooks are being blocked

Cause: monitoring services and webhook senders run from cloud ranges and from countries your visitors do not use.

Fix: list their paths in IPGEO_BYPASS_PATHS , list their addresses in IPGEO_BYPASS_IPS , or give the monitor a header with IPGEO_BYPASS_TOKEN .