KnowledgeMarkG Dev Notes

Deploying Next.js on IIS and Plesk: The Windows Traps Nobody Documents

Kausar Raza — Mon, 02 Nov 2026 08:17:48 GMT

Originally published on knowledgemarkg.com.

Search for how to deploy Next.js on IIS and you will find the same answer repeated: install Application Request Routing, run the app under PM2, and point an IIS reverse proxy rule at localhost:3000. That is good advice if you own the server. On Plesk shared Windows hosting you cannot install ARR, you cannot run PM2 as a service, and you cannot edit applicationHost.config.

This site runs on that stack. What follows is the configuration that actually works, plus the four failures that cost me real hours - each one silent, and each one looking like a different problem than it was.

What you are actually working with

Plesk's Windows Node.js support runs your app through iisnode, an IIS module that hosts a Node process inside IIS rather than beside it. There is no second port, no PM2, no reverse proxy. IIS owns the request, hands it to Node, and takes the response back.

That last part matters more than it sounds. It is where the 404 problem further down comes from.

Build for standalone output

Set the output mode in next.config.ts:

const nextConfig = {
  output: "standalone",
};
export default nextConfig;

A standalone build produces a self-contained server.js plus a pruned node_modules holding only what the app actually imports. On shared hosting, where you are not running npm install on the server, that is the difference between a 25 MB upload and a 400 MB one.

The trap is that next build does not put everything you need into .next/standalone. Two directories are left out by design, and the app boots perfectly without them:

.next/static → copy to .next/static in the deploy folder
public → copy to public in the deploy folder

Miss either one and you get a 200 response, correct HTML, and a completely unstyled page with no JavaScript. Nothing errors, nothing logs.

What the deploy folder has to look like

Because you are assembling the folder by hand rather than letting a platform do it, it helps to know exactly what the finished thing contains. Mine is produced by a script, and the layout is:

deploy-folder/
  server.js            <- from .next/standalone
  app.js               <- the iisnode shim, written by hand
  web.config           <- written by hand
  package.json         <- written by hand, not the project one
  node_modules/        <- from .next/standalone, already pruned
  .next/
    BUILD_ID
    server/            <- from .next/standalone
    static/            <- copied separately, see above
  public/              <- copied separately, see above

Two of those are worth a comment. The package.json at the root is not your project's - it is a minimal file telling the host what to start. And if you script this copy on Windows, force long-path support: node_modules nests well past the 260-character limit, and without the extended-length prefix the copy fails silently part-way through, leaving you with a folder that looks complete and boots to an error.

Finally, anything in public/ that proves ownership of the domain - a Search Console verification file, an IndexNow key file - has to survive every deploy. Both fail silently and slowly if they go missing: Google quietly unverifies the property, and IndexNow rejects every submission. Add an assertion to your staging script so a missing verification file fails the build rather than the search engine.

The web.config that works

Keep it minimal. Every section you add is a section that might be locked at server level:

The handler path has to match a real file, so app.js is a two-line shim that requires the standalone server:

process.env.PORT = process.env.PORT || 3000;
require("./server.js");

Trap 1: one locked section takes the whole site down

Shared hosting locks several system.webServer sections at server level - is the usual culprit. Writing a locked section into your site's web.config does not produce a message about that section. IIS fails to parse the entire file, and every URL returns an empty HTTP 500, including static files that never reach Node.

It reads exactly like an application crash. It is a configuration parse error. The distinguishing signal is that /favicon.ico fails too - if Node were the problem, static files would still serve.

Keep a known-good copy of web.config beside the live one so the rollback is a file copy rather than a debugging session.

One correction to the folklore: is widely assumed to be locked and frequently is not. Plesk's own "Custom error documents" feature writes that exact section into site web.config files, which it could not do if the section were locked. Test it rather than avoiding it - and test by loading your homepage, not a 404, because a locked section breaks everything, not just error pages.

Trap 2: IIS throws away your custom 404 page

This one is invisible unless you go looking. Your app/not-found.tsx renders correctly, the status code is a correct 404, and visitors still get the grey IIS page reading 404 - File or directory not found.

Here is how to prove where it happens. Request a missing URL and read the headers:

curl -s -D - -o /dev/null https://example.com/no-such-page

If the response carries x-nextjs-cache and x-nextjs-prerender headers but the body is about 1 KB of Verdana-styled HTML, then Next rendered your page and IIS replaced the body afterwards. The headers survive the swap; the body does not. That single detail is what tells you to stop debugging your Next.js route and go and look at IIS.

The cause is IIS's existingResponse behaviour, which defaults to replacing the body of any response with an error status. One line fixes it:

Two things worth knowing. First, this is presentation, not SEO: the status code was a correct 404 the whole time, so search engines were never misled and nothing was indexed that should not have been. Second, once IIS stops replacing error bodies it also stops masking 500 bodies - which is exactly why devErrorsEnabled is false in the config above.

Trap 3: environment variables are not what you think

Two rules catch people on every Next.js host, and they bite harder on shared hosting where the control panel offers you an environment-variable editor that looks authoritative.

NEXT_PUBLIC_* is inlined at build time. Anything with that prefix is compiled into the JavaScript bundle during next build. Setting it in Plesk's Node.js panel afterwards does nothing whatsoever, because the string is already baked in. If it has to change, you rebuild.

.env.local loads in production builds too, and it wins. It is not a development-only file, and it overrides .env.production. I wrote about how .env.local silently overrides .env.production separately, because it once baked a localhost API URL into a live build. The safest habit is to name the file .env.development.local, which cannot load in a production build by accident.

Trap 4: deploy order, because Windows locks files

Windows holds a lock on files the running process has open. Extract a new build over a running app and the extract silently skips the locked files - while still reporting success. You end up with a half-updated application and no error anywhere.

The order that works:

Put an app_offline.htm in the application root. IIS stops the app and serves that file for every request.
Delete the old files.
Extract the new build.
Remove app_offline.htm.

Before uploading, confirm the archive actually contains the change you made. A stale build zips just as happily as a fresh one:

grep -rl "a string unique to this change" staging/.next/static/chunks | head

What you do and do not have to redeploy for

Because every deploy here is a manual zip-and-extract, it is worth being clear about which changes actually need one. On this setup, with incremental regeneration doing the work:

No redeploy needed - new or edited content coming from your API or database, and anything a route handler builds from it. If your sitemap route has revalidate = 3600, a new page appears in it within the hour on its own.
Redeploy needed - anything compiled: components, metadata exported from a page, next.config redirects, and every NEXT_PUBLIC_* value.

One consequence worth internalising: a stale cached page can make you think a code fix did not work. After a deploy I checked a page, found the new metadata missing, and nearly started debugging - the response header said x-nextjs-cache: STALE, meaning the old body was being served while the page regenerated behind it. The next request was correct. Check that header before you conclude anything about a deploy.

The other half of that rule is the one people get wrong in the opposite direction: a route handler can only output a field the API already returns. Shipping the frontend first and the backend later gives you a sitemap that silently omits everything.

Debugging a 500 you cannot see

If the app will not boot you get a 500 with an empty body and nothing to read. Turn iisnode's diagnostics on temporarily:

That writes stdout and stderr into an iisnode folder beside the app and puts the error detail in the response body. Read it, fix the boot failure, then turn both back off - especially with existingResponse="PassThrough" enabled, because together they will show stack traces to the public.

One more: if Plesk's Node.js panel offers to "Auto-configure" the application, decline. It generates its own web.config and overwrites yours, including the handler path and the rewrite rule the standalone build depends on.

Is this the right place to host Next.js at all?

Usually not, if you have a free choice. A small Linux VPS running the standalone server behind nginx is simpler in every way and the tooling assumes it. The reason to do this is that something else already lives on the Windows box - an ASP.NET Core API, a SQL Server database, or a client who buys Windows hosting and is not going to move.

That is the situation this site is in, and it works fine. It is only that nothing warns you about the four failures above, and every one of them presents as something other than what it is. If you are still weighing platforms, I compared Windows VPS against Linux VPS for ASP.NET Core and most of that reasoning carries over. If you are newer to the framework itself, the complete Next.js tutorial is a better starting point than the host.

FAQ

Can you run Next.js on IIS without a reverse proxy?

Yes. iisnode hosts the Node process inside IIS, so there is no second port and no reverse proxy rule. This is what Plesk's Windows Node.js support uses, and it is the only option on shared hosting where you cannot install Application Request Routing.

Why is my Next.js site loading with no CSS after deploying to IIS?

A standalone build does not include .next/static or public. Both have to be copied into the deploy folder yourself. The app boots and returns correct HTML without them, so nothing errors - you just get an unstyled page.

Why does IIS show its own 404 page instead of my Next.js not-found page?

IIS replaces the body of any error-status response by default. Adding httpErrors existingResponse="PassThrough" to web.config fixes it. You can confirm that is the cause by checking whether the 404 response still carries x-nextjs-cache headers: if it does, Next rendered the page and IIS swapped the body out afterwards.

Why does every URL return an empty 500 after I edited web.config?

A system.webServer section locked at server level makes IIS fail to parse the whole file, not just that section. Static files fail too, which is how you tell it apart from an application crash. Remove the section you added and the site comes straight back.

Why is my NEXT_PUBLIC environment variable empty in production?

NEXT_PUBLIC_ values are inlined into the JavaScript bundle during next build. Setting them on the server or in Plesk's Node.js panel afterwards has no effect, because the value is already compiled in. Change it and rebuild.

Why did my deploy only partly update the site?

Windows locks files the running process has open, and extracting over a running app silently skips them while still reporting success. Drop an app_offline.htm in first, delete the old files, extract, then remove it.

Is Plesk on Windows a reasonable place to host Next.js?

It works, but it is rarely the easiest choice. It makes sense when something else already requires the Windows box, such as an ASP.NET Core API or SQL Server. If the stack is yours to pick, a small Linux VPS running the standalone server is simpler and far better documented.

Related on knowledgemarkg.com

Deploying ASP.NET Core to Plesk on Windows: Every Error I Hit and What It Actually Meant

Kausar Raza — Mon, 02 Nov 2026 08:15:22 GMT

Originally published on knowledgemarkg.com.

Every guide to deploying ASP.NET Core on Plesk says the same four things: install the hosting component, run dotnet publish, upload the folder, set the application pool. That is all correct, and I have never had a deploy where those four steps were the hard part.

The hard part is everything that happens after, where the server answers with a three-digit sub-code and no explanation. This is that list, in the order you actually meet it. This site's API runs on Plesk shared Windows hosting, so all of it is first-hand.

Publish the right thing first

dotnet publish src/YourApi/YourApi.csproj -c Release -o ./publish

Upload the contents of publish, not the folder itself. Framework-dependent is fine and much smaller, as long as the server has the matching runtime — which is the first thing that goes wrong.

500.31 — the runtime is not there

Full text: Failed to load ASP.NET Core runtime.

The server does not have the ASP.NET Core Hosting Bundle for your target framework, or has an older one. Note it is the Hosting Bundle specifically, not the SDK and not the plain runtime: the bundle is what installs the ASP.NET Core Module into IIS.

On shared hosting you cannot install it yourself. Two options: ask support which versions are installed and target one of those, or publish self-contained so the runtime travels with the app. Self-contained turns a 6 MB upload into about 70 MB, which is a fair trade for not filing a support ticket every time .NET ships a major version.

500.30 — the app started and then died

Full text: ASP.NET Core app failed to start. The module launched your process and the process exited. Three causes cover almost all of it.

The application pool is wrong. It must be set to No Managed Code. ASP.NET Core does not run on the .NET CLR that the pool loads, and a pool set to "v4.0" will fail in a way that looks like your code crashed.

Configuration is missing at runtime. Anything the app reads during startup — a connection string, an API key — that is present on your machine and absent on the server will throw before the first request is served.

Something in Program.cs throws. Which you cannot see, until you turn the log on:

Create the logs folder yourself — the module will not create it, and if it cannot write there you get the same blank 500.30 with no log. Read the stack trace, fix it, then set stdoutLogEnabled back to false. It is not a logger; it grows forever.

500.19 — IIS could not read your web.config

This is the one that fools people, because it has nothing to do with your application. IIS failed to parse the configuration file, so the app never started at all.

On shared hosting the usual cause is a locked section. Hosts lock parts of system.webServer at server level, and writing a locked section into your site's web.config makes IIS reject the entire file — not just that section.

The giveaway: static files fail too. If a plain text file in the same folder also returns 500, the problem is configuration, not code.

Keep the file to the minimum ASP.NET Core actually needs:

One piece of folklore worth correcting: not every section people assume is locked actually is. On this host turned out to be allowed, and I had avoided it for months on the strength of a warning I had written myself. Test a section before you rule it out — but test by loading a page you know works, because a locked section breaks everything at once.

app_offline.htm "not working", and the deploy order that fixes it

Drop a file called app_offline.htm in the application root and the ASP.NET Core Module shuts the app down and serves that file to every request. Remove it and the app restarts. It is the cleanest maintenance switch IIS has.

When people say it does not work, it is almost always one of these:

Wrong name or place. It must be exactly app_offline.htm — not .html, not App_Offline.htm in a subfolder — and it must sit next to web.config in the application root, not the site root.
Windows hid the extension from you. You created app_offline.htm.txt and Explorer is showing you app_offline.htm.
In-flight requests. Only new requests get the offline page; existing ones finish normally.

The reason it matters on Windows is the thing it protects you from. Windows locks files that a running process has open. Extract a new build over a running app and the extract skips the locked DLLs — and Plesk's extract still reports success. You get a half-updated application, a version mismatch, and no error anywhere.

So the order is not optional:

Upload app_offline.htm to the application root.
Delete the old files.
Extract the new build.
Delete app_offline.htm.

appsettings.Production.json does not replace appsettings.json

It layers on top of it. Keys present in both are overridden by the environment file; keys that exist only in the base file still apply.

That cuts both ways and both have bitten me. A key you thought you had overridden is still being read from the base file because you spelled the section differently. And a key you assumed was dead because it is not in the production file is very much alive.

If a setting is not behaving, log the resolved value at startup once rather than reasoning about which file won:

app.Logger.LogInformation("Using provider {Provider}",
    builder.Configuration["Email:Provider"] ?? "(null)");

And keep appsettings.Production.json out of source control — it holds the real connection string. Copy it forward from the previous deploy rather than regenerating it, or you will overwrite live credentials with Server=localhost;Database=dev;User Id=sa;Password=changeme; and spend an hour on a 500.30 that is really a login failure.

__EFMigrationsHistory drift

EF Core records applied migrations in a table called __EFMigrationsHistory, keyed on the migration's ID — the timestamp in its filename. That ID is the only thing EF compares.

Here is how it goes wrong. A migration is applied to production. Later, someone regenerates that migration — a rename, a rebase, a merge that recreated the file — and it comes back with a new timestamp. EF now sees an ID it has no record of, concludes the migration has never run, and tries to apply it again. On a table that already exists, that fails.

The fix is to tell the history table what it already knows, idempotently, so re-running it is harmless:

IF NOT EXISTS (SELECT 1 FROM __EFMigrationsHistory
               WHERE MigrationId = N'20260927134609_AddSomeColumn')
BEGIN
    INSERT INTO __EFMigrationsHistory (MigrationId, ProductVersion)
    VALUES (N'20260927134609_AddSomeColumn', N'9.0.0');
END

Do not delete rows from this table to "force a rerun" unless you have checked that the migration is genuinely reversible against live data. It is a ledger, not a cache.

Give yourself a way to tell which build is live

Because a Windows deploy can half-succeed, "did my change actually ship?" is a question you will ask often. Guessing from behaviour is slow. A tiny unauthenticated endpoint answers it in a second:

app.MapGet("/api/v1/version", () => new
{
    version = typeof(Program).Assembly.GetName().Version?.ToString(),
    built = System.IO.File.GetLastWriteTimeUtc(
        typeof(Program).Assembly.Location).ToString("u"),
});

One warning from my own code, which I am in the middle of fixing. When I first added this I also returned the assembly's full path, because it was useful while debugging a deploy that had half-extracted. That ships the absolute directory layout of the server to anyone who asks, and it stayed in production far longer than the debugging session did.

Return a version and a timestamp. Do not return paths, environment variables, connection state, or the machine name. If you need those while chasing a problem, add them for the hour and take them out again — a diagnostic endpoint is the easiest thing in a codebase to forget about, because it never breaks and nothing tests it.

One last thing: the database is probably not local

On shared hosting your SQL Server usually lives on a different box, sometimes a different datacentre. Every query crosses a network, and the first one after an idle period pays a cold start. Local development against that database feels broken when it is merely remote.

This is worth knowing before you spend an afternoon profiling EF Core over a 40 ms round trip. Measure against the server, not your laptop, and judge a query by its round-trip count before its execution plan.

Is Plesk the right place for this?

If the API is the only thing you are hosting, a small Linux VPS running Kestrel behind nginx is simpler and better documented. Plesk on Windows earns its place when something else already requires that box — a SQL Server licence, a legacy ASP.NET app, or a client who buys Windows hosting and will not move.

That is the situation here, and it is stable once the five problems above are behind you. If you are running the front end on the same stack, I wrote up the matching set of traps for Next.js on IIS and Plesk — different runtime, same hosting model, and a couple of the failures are identical. And if you are still choosing, this is the Windows VPS versus Linux VPS comparison I would read first.

FAQ

What does ASP.NET Core error 500.31 mean?

The ASP.NET Core Hosting Bundle for your target framework is not installed on the server, or is an older version. It must be the Hosting Bundle, not the SDK or the plain runtime, because the bundle is what installs the ASP.NET Core Module into IIS. On shared hosting, either target a version the host already has or publish self-contained.

How do I fix ASP.NET Core 500.30, app failed to start?

The process launched and exited. Check that the application pool is set to No Managed Code, that every setting the app reads at startup exists on the server, and then turn on stdoutLogEnabled in web.config to read the actual exception. Create the logs folder yourself - the module will not, and without it you get the same blank error with no log.

Why do I get HTTP Error 500.19 on IIS?

IIS could not parse web.config, so your app never started. On shared hosting the usual cause is a system.webServer section the host locks at server level; writing one makes IIS reject the whole file rather than that section. The giveaway is that static files in the same folder fail too.

Why is app_offline.htm not working?

Usually the name or the location. It must be exactly app_offline.htm, in the application root next to web.config, not the site root - and check Windows is not hiding a .txt extension from you. Requests already in flight also finish normally; only new ones get the offline page.

Does appsettings.Production.json replace appsettings.json?

No, it layers on top. Keys in both are overridden by the environment file, but keys that exist only in the base file still apply. If a setting is not behaving, log the resolved value at startup rather than reasoning about which file won.

Why is EF Core trying to apply a migration that already ran?

EF compares the migration ID, which is the timestamp in the filename. If the migration file was regenerated after it was applied, it comes back with a new timestamp, so EF sees an ID it has no record of and runs it again. Insert the new ID into __EFMigrationsHistory idempotently rather than deleting rows.

Can you deploy ASP.NET Core to Plesk shared hosting at all?

Yes, and it is stable once configured. You cannot install the Hosting Bundle or edit applicationHost.config yourself, so you work within what the host allows. It makes most sense when something else already requires the Windows box, such as a SQL Server licence or a legacy ASP.NET application.

Related on knowledgemarkg.com

Your Next.js Page Is Not Updating: Read the x-nextjs-cache Header Before You Debug Anything

Kausar Raza — Mon, 02 Nov 2026 08:13:33 GMT

Originally published on knowledgemarkg.com.

You shipped a change. The database has it, the build succeeded, the deploy finished. You load the page and it shows the old content.

At this point most people start debugging the thing they just changed. Nine times out of ten on a Next.js site, nothing is broken. Before you touch anything, send one request and read one header:

curl -s -D - -o /dev/null https://example.com/the-page | grep -i x-nextjs-cache

That header separates "my deploy failed" from "the page is simply stale", and those are completely different problems. I have confused them three times in two days on this site, and twice I reached a wrong conclusion and had to walk it back.

What the values mean

x-nextjs-cache reports how the response you just received was produced:

HIT — served from the cache, and the cached entry is still considered fresh. What you see is what the cache holds.
MISS — nothing in the cache for this path, so it was rendered now. The content is current.
STALE — this is the one that fools you. The cached entry has passed its revalidation window, so the server handed you the old body and kicked off a regeneration in the background. Your next request will almost certainly be fresh.

Read that third one again, because it is the whole article. A STALE response is not a failure. It is the cache doing exactly what it was configured to do: never make a visitor wait for a rebuild. The cost is that the first person to ask for an expired page gets yesterday's copy.

The trap, with the actual numbers

I had just fixed a metadata bug and deployed it. To verify, I crawled every URL in the sitemap and checked whether the new tag was present. Result: 175 of 177 pages correct, two pages missing the tag.

Two pages. That looks exactly like a real bug — some code path the fix missed. I was already forming a theory about which one.

Then I requested one of those two pages again and read the headers:

x-nextjs-cache: STALE

The page had not missed the fix. It was serving a copy generated before the deploy, while regenerating behind the scenes. The very next request returned the correct tag. There was no bug. There had never been a bug.

It gets worse, in an interesting way. Earlier the same day I ran two tools over the site back to back — a crawler, then a content scanner. The crawler reported dead links that the scanner, running two minutes later, could not find. Both were correct. The crawler's own requests were what expired the cache and triggered regeneration, so by the time the second tool ran it was reading freshly generated pages. The first tool measured the old world; the second measured the world the first tool had created.

If you take one habit from this: when a verification result surprises you, request the page a second time before you believe it.

What actually controls this

For a route segment, the revalidation window is an export:

// app/blog/[slug]/page.tsx
export const revalidate = 3600;   // seconds

That means: serve from cache for an hour; after the hour, the next request gets the stale copy and triggers a rebuild. It does not mean "rebuild every hour" — nothing regenerates if nobody asks. A page nobody visits stays stale indefinitely, which is why a low-traffic site can show week-old content and a busy one feels instant.

Two values are worth knowing:

export const revalidate = 0 — never serve from the cache; render per request.
export const dynamic = "force-dynamic" — the same effect, stated as intent.

A sitemap route handler with revalidate = 3600 is a good illustration. Publish a post and it will not appear in sitemap.xml immediately. It appears within the hour, with no deploy and no manual step. I watched this happen yesterday: the post went live, the sitemap still listed 61 URLs, and an hour later it listed 62. Nothing was broken in between.

When a timer is the wrong tool

Time-based revalidation assumes the content changes on its own schedule. It is the wrong tool when you change something and need it live now — particularly when the change was made outside the application.

That is the case people hit most often and understand least. If you update rows with a SQL script, or edit content in a CMS that your app does not know about, the app has no idea anything happened. No amount of redeploying helps, because the deploy is not what is stale — the cache entry is.

For that, invalidate explicitly:

import { revalidatePath, revalidateTag } from "next/cache";

// after a write that the app performed
revalidatePath("/blog/the-slug");
revalidateTag("posts");

Two things catch people here. revalidatePath only runs on the server — in a route handler or a server action — so calling it from a client component does nothing. And it marks the entry stale rather than rebuilding immediately, so the very next request may still return the old body with x-nextjs-cache: STALE. That is not a failure either.

What a deploy does and does not clear

This depends on your host more than on Next.js, which is why the answers you find online contradict each other.

On a platform that builds fresh and discards the old filesystem, a deploy effectively clears everything. On a self-hosted setup where you extract a build over the previous one, whether the on-disk cache survives depends on whether you deleted it. If your deploy copies files over the top without removing .next/cache, entries can outlive the deploy that was supposed to replace them.

Worth separating from a related failure that looks identical: on Windows, a running process holds locks on files, so an extract over a live app silently skips them and reports success anyway. That produces a genuinely half-updated app, not a stale cache — and the header will say HIT or MISS rather than STALE. I covered that one, and the deploy order that avoids it, in the Next.js on IIS and Plesk write-up.

Three caches, and only one of them is this header

A lot of the contradictory advice online comes from people solving a different layer and assuming it was the same one. There are usually three between your render and the visitor's screen:

The Next.js data and route cache — on your server, reported by x-nextjs-cache. This is the one revalidate and revalidatePath control.
A CDN or reverse proxy in front of it, obeying cache-control. It can keep serving an old body long after Next.js has regenerated, and x-nextjs-cache will never tell you, because the response may not have reached Next.js at all.
The browser. Cheap to rule out, so rule it out first.

Two more headers help you tell them apart. age is how many seconds an intermediate cache has been holding the response — a large and growing age on a page you keep requesting means something in front of your server is answering. And x-nextjs-prerender tells you the page was prerendered rather than rendered per request, which is useful when you expected a route to be dynamic and it is not.

The practical ordering: hard-refresh once to eliminate the browser, then compare curl against what the browser shows. If curl is correct and the browser is not, it is local. If both are wrong but x-nextjs-cache says MISS, you are probably looking at something in front of Next.js, not Next.js itself.

Reading it without curl

In Chrome or Firefox DevTools, open the Network tab, tick Disable cache, reload, click the document request — the very first one, not an asset — and read Response Headers. The value is there on every request Next.js serves, so you can watch it flip from STALE to HIT on a second reload without leaving the browser.

One caveat that wastes time: if you are looking at a client-side navigation rather than a full page load, there is no document request to inspect. Reload the URL directly.

A checklist for "is my change actually live?"

Request the page twice. If the second response differs from the first, you were looking at a stale entry, not a bug.
Read x-nextjs-cache. STALE means wait and retry; HIT or MISS with wrong content means something real is wrong.
Check the content at the source. Hit your API or query the database directly. If the source is wrong, the cache is innocent.
Decide which layer is stale. Content changed outside the app needs revalidatePath, not a redeploy. Code changes need a deploy, and a timer will never fix them.
Only then start debugging.

Compiled things — components, exported metadata, redirects in next.config, anything with a NEXT_PUBLIC_ prefix — always need a rebuild, because they are baked in at build time. That last one catches people constantly; I wrote about a related environment-variable trap in how .env.local silently overrides .env.production. If you are newer to the framework, the complete Next.js tutorial covers the rendering model this builds on.

The short version

A page showing old content is usually not a broken deploy. It is a cache entry doing its job, and one header tells you which. Checking it costs one request. Not checking it cost me two wrong conclusions in two days, and both times I was already three steps into debugging code that was working perfectly.

FAQ

What does x-nextjs-cache: STALE mean?

The cached copy has passed its revalidation window, so Next.js served you the old body and started regenerating the page in the background. It is not an error. Request the page again and you will almost certainly get the fresh version.

What is the difference between HIT, MISS and STALE?

HIT means it came from the cache and is still considered fresh. MISS means there was nothing cached so it was rendered now, which makes it current. STALE means the entry expired, you received the old body, and a rebuild was triggered behind your request.

Why is my Next.js page not updating after deploy?

Request it twice and read x-nextjs-cache. If the first response is STALE and the second is correct, nothing was wrong. If it says HIT or MISS and the content is still wrong, then check the source data and whether the deploy actually replaced the files.

Does export const revalidate = 3600 rebuild the page every hour?

No. It means the cached copy is considered fresh for an hour. Nothing regenerates unless someone requests the page after that window, so a page nobody visits can stay stale indefinitely.

Why is revalidatePath not working?

Two usual reasons. It only runs server-side, so calling it from a client component does nothing. And it marks the entry stale rather than rebuilding immediately, so the next request can still return the old body with a STALE header before the fresh one appears.

I changed data directly in the database and the page still shows the old content.

The application never saw the change, so nothing invalidated the cache, and redeploying will not help because the deploy is not what is stale. Either call revalidatePath for the affected routes, or wait out the revalidate window on that route.

Does deploying clear the Next.js cache?

It depends on the host. A platform that builds fresh and discards the old filesystem effectively clears it. On a self-hosted setup where you extract a build over the previous one, cache entries can survive unless you delete .next/cache as part of the deploy.

Related on knowledgemarkg.com

ASP.NET Core 'Error Unprotecting the Session Cookie': Why Your Keys Disappear on Deploy

Kausar Raza — Mon, 02 Nov 2026 08:11:39 GMT

Originally published on knowledgemarkg.com.

You deploy an ASP.NET Core app, or IIS recycles its app pool overnight, and the log fills up with this:

warn: Microsoft.AspNetCore.Session.SessionMiddleware[7]
      Error unprotecting the session cookie.
      System.Security.Cryptography.CryptographicException: The key {83f2e736-3392-4263-9f0f-ad943c51fe3e} was not found in the key ring.

At the same time, users report being logged out, and forms fail with "The antiforgery token could not be decrypted". The session warning is just the visible part. The cause is that the app has lost the keys it used to encrypt its cookies. Every cookie issued before that moment is now unreadable.

This happened on the API behind this site. It runs on IIS under Plesk, where the app pool has no loaded user profile, so ASP.NET Core kept its keys in memory and threw them away on every restart. Below is what I reproduced, the exact messages each cause produces, and the fix. The deploy side of IIS and Plesk 500 errors is in the Plesk 500 errors post.

The short fix: store the Data Protection keys in a folder that survives restarts and deploys, and give the app a fixed name: services.AddDataProtection().PersistKeysToFileSystem(new DirectoryInfo(@"App_Data\keys")).SetApplicationName("MyApp"). Then make sure your deploy never deletes that folder. Users who already have old cookies will be logged out once more, and after that it stops.

What the error actually means

ASP.NET Core doesn't store session data, login tickets or antiforgery tokens in plain text. It encrypts them with the Data Protection system, which keeps a set of keys called the key ring. Each encrypted payload carries the ID of the key that made it. When a request comes in, the app looks up that ID in its ring. If it isn't there, you get "The key {...} was not found in the key ring".

Three components report it, in three different ways:

Session middleware logs "Error unprotecting the session cookie" as a warning, then quietly starts a new, empty session.
Cookie authentication logs "Cookies was not authenticated. Failure message: Unprotect ticket failed", but only at Information level. With the default "Microsoft.AspNetCore": "Warning" setting in appsettings.json, you never see it. The user is just signed out.
Antiforgery throws AntiforgeryValidationException: "The antiforgery token could not be decrypted", which usually surfaces as a 400 on form posts.

That's why the session warning is the one people search for. It's the only one that shows up in a default log, even though the logouts hurt more.

What I tested

I built a minimal ASP.NET Core 9 app (runtime 9.0.8, Windows 11, Kestrel) with cookie sign-in, session and antiforgery. I signed in with curl, kept the cookie jar, restarted the app with a different key setup each time, and sent the old cookies back. These are the results.

1. Keys persisted, plain restart: nothing breaks

With keys stored in a folder and the app restarted on the same folder, the user was still signed in and the old antiforgery token still validated. This is the control. One thing did reset: the session value was empty after the restart. That isn't a key problem. AddDistributedMemoryCache() keeps session data in process memory, so a restart loses it even when the cookie decrypts fine. If you need sessions to survive restarts, use SQL Server or Redis for the session store as well.

2. Key folder wiped: "was not found in the key ring"

Pointing the restarted app at an empty folder is exactly what a deploy does when it deletes the old site folder, including App_Data. The user came back anonymous, the antiforgery post failed with "The antiforgery token could not be decrypted", and the log showed the error from the top of this article, naming the old key's ID. The app also silently created a new key, logging:

No XML encryptor configured. Key {53f0f160-...} may be persisted to storage in unencrypted form.

3. Same keys, different application name: "The payload was invalid"

Data Protection isolates apps from one another using an application name. If you don't set one, it is derived from the app's content root path. So moving the site to a different folder, or swapping deployment slots, can change it. I kept the same key folder and changed only SetApplicationName from SiteA to SiteB. The keys were found, but nothing decrypted:

warn: Microsoft.AspNetCore.Session.SessionMiddleware[7]
      Error unprotecting the session cookie.
      System.Security.Cryptography.CryptographicException: The payload was invalid.
info: Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationHandler[7]
      Cookies was not authenticated. Failure message: Unprotect ticket failed

The antiforgery error changed too, to "The required antiforgery cookie ".AspNetCore.Antiforgery.6asUPwDiMTw" is not present". The suffix of that cookie name is derived from the application name, so the app was looking for a cookie with a different name. If you see "payload was invalid" rather than "key not found", look at the application name before the keys.

4. Where the keys go by default

With no configuration, a normal Windows user account gets this at startup:

User profile is available. Using 'C:\Users\\AppData\Local\ASP.NET\DataProtection-Keys' as key repository and Windows DPAPI to encrypt keys at rest.

That's why it works on your machine. An IIS app pool doesn't have that folder unless "Load User Profile" is on, and on shared hosting such as Plesk you often can't control that setting. When there is no profile and no registry hive set up for the pool, the framework uses an in-memory ring. I couldn't reproduce that fallback outside IIS, but its warning is in the framework itself (Microsoft.AspNetCore.DataProtection.dll, 9.0.8):

Neither user profile nor HKLM registry available. Using an ephemeral key repository. Protected data will be unavailable when application exits.

If that line is in your startup log, every app pool recycle, idle timeout and deploy logs your users out.

The fix

Three settings, all in Program.cs before builder.Build(). This is the configuration this site's API uses now:

var keysDir = new DirectoryInfo(Path.GetFullPath("App_Data/keys", builder.Environment.ContentRootPath));
keysDir.Create();

var dataProtection = builder.Services
    .AddDataProtection()
    .PersistKeysToFileSystem(keysDir)          // keys survive restarts and recycles
    .SetApplicationName("MyApp");              // fixed, so moving the folder or slot doesn't change it

if (OperatingSystem.IsWindows())
{
    dataProtection.ProtectKeysWithDpapi(protectToLocalMachine: true);  // encrypt key files at rest
}

Notes on each line:

The folder must be outside the release files. If your deploy copies the site over App_Data, or deletes and re-extracts it, the keys go with it. Keep App_Data out of the delete step, the same way you keep uploads.
Use ProtectKeysWithDpapi(protectToLocalMachine: true), not the per-user default. An app pool has no user profile to hold a per-user DPAPI key. Machine scope works without one. The trade-off is that the key files can only be decrypted on the same machine.
Set the application name once and never change it. Changing it logs every user out, the same as losing the keys.

After the change, the first deploy logs everyone out once. That's expected: the old cookies were encrypted with keys that no longer exist, and there's nothing to recover them with. From then on, restarts and recycles keep the same keys.

How to check it worked

Sign in, then recycle the app pool or restart the app.
Check that you are still signed in. If you are, the keys survived.
Check the log. The "User profile is available" line should be gone, and no "Neither user profile nor HKLM registry available" line should appear. Either one would mean the keys went to memory.
Check that App_Data\keys contains key-*.xml files, and that the timestamps don't change on every restart.

FAQ

What does 'The key was not found in the key ring' mean in ASP.NET Core?

ASP.NET Core encrypted a cookie or token with a key that the app no longer has. The key ring is empty or missing that key, so the payload can't be decrypted. The usual cause is keys stored in memory, or a key folder that was wiped during a deploy.

Why am I logged out every time I deploy or recycle the app pool?

The Data Protection keys are kept in memory, or in a folder that the deploy deletes. The new process has different keys, so cookies from before can't be decrypted. Persist the keys to a folder outside the release files, with PersistKeysToFileSystem.

What does 'The payload was invalid' mean in ASP.NET Core Data Protection?

The app found the key but the cookie still couldn't be decrypted. A common cause is a different application name. Check SetApplicationName, and check that the app isn't running from a different folder or deployment slot with a different default name.

What is the difference between 'key not found' and 'payload was invalid'?

'Key not found' means the key ring doesn't contain the key that encrypted the cookie, so the keys were lost or moved. 'Payload was invalid' means the key was found, but the app name or key data doesn't match. Keys first, then application name.

Where should ASP.NET Core store Data Protection keys on IIS?

In a folder that the app pool identity can write to, outside the release folder, for example App_Data/keys. Protect the key files with ProtectKeysWithDpapi(protectToLocalMachine: true), since an app pool usually has no user profile for per-user DPAPI.

What does 'No XML encryptor configured' mean?

The Data Protection keys are being saved to disk without encryption. It's a warning, not an error. Fix it with ProtectKeysWithDpapi on Windows, or with a certificate or Key Vault on other hosts.

Does the session warning 'Error unprotecting the session cookie' mean my users are logged out?

Not directly. It's the session middleware, which starts an empty session. Login is handled by cookie authentication, which logs a separate message at Information level. Check that too, because the warning alone doesn't show it.

Related on knowledgemarkg.com

sqlcmd 'Scripting Variable Not Defined': Why $( Breaks Your Script and How to Fix It

Kausar Raza — Mon, 02 Nov 2026 08:05:11 GMT

Originally published on knowledgemarkg.com.

If you run SQL scripts through sqlcmd - a deploy step, a data fix, a seed script, a pipeline that loads text into a table - sooner or later one of them prints this:

'Amount' scripting variable not defined.

The name in quotes changes; the cause doesn't. Somewhere in your script there is a $( followed by a name and a ), and sqlcmd has read it as one of its own variables. Usually it's inside a string you meant literally: a price template, a shell command stored in a table, a blog post with a code sample in it. I hit it on this site, whose posts are inserted by a script that pipes generated SQL through sqlcmd - any post with a shell example like $(cygpath -w file) in it tripped over this.

The short fix: if the script doesn't use sqlcmd variables at all, run it with sqlcmd -x (or Invoke-Sqlcmd -DisableVariables in PowerShell). If it does use them, break the pattern inside the SQL text instead: write '$' + '(Amount)' or CHAR(36) + '(Amount)'. And if you build the command in Bash or PowerShell, put the query in single quotes - in double quotes the shell eats $(...) before sqlcmd ever sees it.

That's the fix. What makes this worth an article is that the error message is the least dangerous thing sqlcmd does with $(...) - the dangerous cases print nothing at all.

What sqlcmd is doing

sqlcmd is not just a pipe to SQL Server. Before it sends each batch, it runs its own pre-processor over the text, and one of that pre-processor's jobs is replacing $(Name) with the value of a scripting variable called Name. This is a feature: it lets one script run against different databases or servers.

:setvar TargetDb "Shop_Staging"
USE $(TargetDb);
SELECT COUNT(*) FROM dbo.Orders;

The catch is that the pre-processor doesn't care about T-SQL quoting. It replaces $(Name) inside string literals - '...' and N'...' - exactly as it does in code. To sqlcmd, 'Total: $(Amount)' is a variable reference wrapped in some characters that happen to be quotes.

A value for a variable can come from five places. From lowest to highest precedence, according to Microsoft's documentation:

system-level environment variables
user-level environment variables
variables set in the shell before starting sqlcmd (SET X=Y, export X=Y)
sqlcmd -v X=Y
:setvar X Y inside the script

Only if none of the five has a value do you get "scripting variable not defined". Keep the first three in mind - they are where the silent failures come from.

What I tested

Everything below was run on 26 October 2026 with the classic ODBC-based sqlcmd (version 15.0.1300.359, Windows) against SQL Server 2022, using only SELECT and PRINT. The test script is one line:

SELECT 'Total: $(Amount)' AS r;

1. Without -b, the error doesn't stop anything

Run it plainly and you get the message on stderr - and the query still runs, with the literal text left in:

r
-
Total: $(Amount)

(1 rows affected)
'Amount' scripting variable not defined.

The exit code is 0. If this script were an INSERT, the row would be saved exactly as written, and any CI job checking the exit code would report success. Microsoft's own page contradicts itself here: one sentence says "the execution of the script stops", while a worked example further down shows the row being returned. The example - and my test - are right. It only stops when you pass -b.

2. With -b, it stops - halfway through

With -b, the batch containing the reference is never sent and sqlcmd exits with code 1. But batches before it have already run. A three-batch script printed batch 1 ran, then the error, then nothing. If the script isn't wrapped in a transaction, you are left with the first half applied. That's still the behaviour you want in automation - just know that "failed" doesn't mean "nothing happened".

3. Environment variables fill it in - silently

This is the one that actually corrupts data. I changed the test string to:

SELECT 'path=$(USERNAME)' AS envleak, '$(SQLCMDSERVER)' AS srv;

No message, exit code 0, and the result came back with my Windows user name in place of $(USERNAME) and the server's address in place of $(SQLCMDSERVER). sqlcmd treats every environment variable as a scripting variable, and it defines a set of its own (SQLCMDSERVER, SQLCMDUSER, SQLCMDDBNAME and more). So a stored string that happens to contain $(PATH), $(TEMP), $(COMPUTERNAME) or $(HOME) is quietly rewritten with values from whatever machine ran the script - including, on a build agent, paths and account names you didn't mean to put in your database. Names are case-insensitive too: -v AMOUNT=5 filled in $(amount).

The visible error only appears when the name matches nothing. You only get a warning when you're lucky.

4. A broken pattern is a syntax error

An unclosed $( or a name with a space in it gives a different message:

Sqlcmd: Error: Syntax error at line 1 in file 't7.sql'.

Here the batch is not sent - but without -b the exit code is still 0, so the script "succeeds" having skipped that statement.

5. Things that turned out to be fine

Some things I expected to break and didn't, in this version:

$(Anything) inside a -- or /* */ comment produced no message.
A multi-line string literal containing a line that starts with GO, :setvar or !!echo was kept as text. sqlcmd did not split the batch, set a variable or run a shell command.

So it's specifically $(...) in code and string literals you need to watch.

Fix 1: turn variables off with -x

If the script never uses sqlcmd variables, this is the whole fix:

sqlcmd -S myserver -d Shop -x -b -i load_content.sql

-x makes sqlcmd ignore scripting variables completely - no substitution, no message, the text goes to SQL Server as written. It's an all-or-nothing switch: in my test, -x together with -v Amount=19.99 still produced the literal $(Amount), and :setvar inside the file was ignored as well. If the script relies on $(TargetDb) somewhere, -x breaks that.

Keep -b alongside it, so real SQL errors still fail the run.

PowerShell: Invoke-Sqlcmd -DisableVariables

The SqlServer module's Invoke-Sqlcmd uses the same variable syntax, and its equivalent of -x is -DisableVariables. Microsoft's documentation describes it in nearly the same words as -x - "useful when a script contains many INSERT statements that may contain strings that have the same format as variables". (I didn't have the module installed for this test, so this one is from the docs, not from a run.)

Invoke-Sqlcmd -ServerInstance myserver -Database Shop -InputFile .\load_content.sql -DisableVariables

Fix 2: break the pattern inside the SQL

When the script needs variables and contains literal $(...) text, change how the text is written so the pre-processor never sees $(. Both of these came back as the literal Total: $(Amount) with no message:

SELECT 'Total: $' + '(Amount)'          AS concat_fix,
       'Total: ' + CHAR(36) + '(Amount)' AS char_fix;

CHAR(36) is the dollar sign. Use NCHAR(36) and N'...' for nvarchar data. There is no escape sequence for $( in sqlcmd - splitting it is the workaround. If you generate SQL from code, do the split in the generator so nobody has to remember it by hand:

def sql_literal(text):
    # N'...' with quotes doubled, and "$(" split so sqlcmd can't see a variable
    body = text.replace("'", "''").replace("$(", "$' + N'(")
    return "N'" + body + "'"

The same goes for SQL database projects and SSMS in SQLCMD mode, which use the same $(Name) syntax for their variables. I haven't tested those here, but the split string has no $( in it for any of them to find.

Fix 3: check what your shell did first

A related trap sits one layer earlier, in the shell. Both Bash and PowerShell use $(...) for their own command substitution, and both expand it inside double quotes before sqlcmd starts:

$ q="SELECT 'Total: $(Amount)' AS r"; echo "$q"
bash: Amount: command not found
SELECT 'Total: ' AS r

PowerShell does the same and says The term 'Amount' is not recognized as the name of a cmdlet, function, script file, or operable program, then hands over SELECT 'Total: ' AS r. The query runs, the value is just gone - and sqlcmd never complains because it never saw a $(. If what comes out has an empty gap where your text was, this is why. Use single quotes in the shell (doubling the inner SQL quotes in PowerShell), escape it as ``$(in a PowerShell double-quoted string, or - better - put the SQL in a file and pass it with-i`.

Which fix to use

Loading content (articles, templates, HTML, anything users wrote): -x or -DisableVariables. You can't predict what text contains, and environment variable substitution makes it unsafe to rely on the error appearing.
Deployment scripts that use variables: keep variables on, split any literal $( with CHAR(36), and always pass -b.
Large or repeated data loads: consider not generating SQL text at all. A parameterised command from your application, bcp or BULK INSERT doesn't put the data through sqlcmd's pre-processor, so there's nothing to escape.

The other sqlcmd defaults that cause trouble

This is the second article I've written about sqlcmd quietly behaving differently from the application that normally talks to the same database. The first was Msg 1934, "SET options have incorrect settings: QUOTED_IDENTIFIER" - the classic sqlcmd starts sessions with QUOTED_IDENTIFIER OFF, which breaks writes to any table with a filtered index. The script that inserts posts on this site now passes both -x and a SET QUOTED_IDENTIFIER ON where it needs one. If you run SQL by hand against a database an ORM normally manages, it's also worth reading about EF Core's "There is already an object named X in the database", which is what happens when hand-run SQL and migration history drift apart.

FAQ

What does 'scripting variable not defined' mean in sqlcmd?

Your script contains $(Name) and sqlcmd treats that as a reference to a scripting variable called Name. It found no value for it in :setvar, -v or the environment, so it prints the message. The text is usually a literal string you didn't mean as a variable.

Does the script stop when sqlcmd says a scripting variable is not defined?

Not by default. In a test with sqlcmd 15, the statement still ran with the literal $(Name) text and the exit code was 0. Only with -b does sqlcmd skip that batch and exit with code 1, and batches before it have already run.

How do I stop sqlcmd from replacing $( in my data?

Run sqlcmd with -x, which turns off scripting variables entirely, or use Invoke-Sqlcmd -DisableVariables in PowerShell. If the script also needs variables, write the dollar sign as CHAR(36) or split the string as '$' + '(Name)' so sqlcmd never sees the $( pattern.

Is there an escape character for $( in sqlcmd?

No. sqlcmd has no escape sequence for the $( pattern. The workarounds are -x to disable variables, or building the text so the two characters are never next to each other in the script, for example CHAR(36) + '(Name)'.

Can environment variables change my data when I run sqlcmd?

Yes. sqlcmd treats environment variables as scripting variables, so a string containing $(USERNAME), $(PATH) or $(TEMP) is silently replaced with that machine's value, with no warning and exit code 0. That's why -x is the safer choice for loading user-written content.

What is the order of precedence for sqlcmd variables?

From lowest to highest: system environment variables, user environment variables, variables set in the shell before starting sqlcmd, the -v option, and :setvar inside the script. Variable names are case-insensitive.

Why is my query empty where $(...) was, with no sqlcmd error?

Your shell probably expanded it first. Bash and PowerShell both treat $(...) inside double quotes as command substitution, so the text is removed before sqlcmd starts. Use single quotes, escape it as `$( in PowerShell, or put the SQL in a file and pass it with -i.

Related on knowledgemarkg.com

IndexNow: What a 202 Actually Means, and Whether Google Cares

Kausar Raza — Mon, 02 Nov 2026 07:53:22 GMT

Originally published on knowledgemarkg.com.

I wired IndexNow into this site this week and learned something in the first ten minutes that is not in most write-ups: the success response you almost certainly got back means nothing.

If you submitted URLs and saw HTTP 202, you have not confirmed anything. I proved that to myself with a deliberately invalid key, and it returned the same 202 as my real one.

Here is what the status codes mean, what Google does with IndexNow, and whether the whole thing is worth half an hour of your time.

The 202 problem

IndexNow's bulk endpoint takes a JSON body with your host, your key and a list of URLs. I submitted 175 URLs pulled from this site's sitemap and got back:

HTTP 202

Which looks like success. It is not. Per the protocol's own specification:

200 OK - URL submitted successfully. The key was validated.
202 Accepted - URL received. IndexNow key validation pending.
400 Bad Request - the request itself was malformed.
403 Forbidden - the key is not valid.
422 Unprocessable Entity - the URLs do not belong to the host, or the key does not match the schema.
429 Too Many Requests - you are submitting too often.

A 202 is a receipt, not a verdict. The engine has taken your payload and will go and check your key later. If that check fails, nothing happens, nobody tells you, and your URLs are silently dropped.

The control experiment

To be sure I was reading that correctly rather than guessing, I sent two single-URL submissions through the GET endpoint - one with my real key, one with thirty-two zeros:

real key    -> HTTP 200
all zeros   -> HTTP 202

That is the whole lesson in two lines. The invalid key produced the more reassuring-looking response of the two, because 202 simply defers the question. The 200 is the only one that tells you the engine went and fetched your key file and was satisfied.

So: verify with a single GET, not with your bulk POST. Submit one URL on its own and look for a 200. Bulk submissions legitimately return 202 and you cannot conclude anything from that either way.

Does Google use IndexNow?

No. This is the most-searched question about the protocol and it has a short answer that a lot of posts talk around.

IndexNow is a Microsoft-led protocol. Bing, Yandex, Seznam and Naver participate. Google announced back in 2021 that it would evaluate it and has never adopted it for indexing. Your IndexNow submission does not reach Google, and Google still has to be told about new pages the old way - a sitemap it crawls on its own schedule, or a manual Request indexing in Search Console.

That makes IndexNow a worthwhile addition to your setup rather than a replacement for any of it. If someone sells it to you as a way to "get indexed by Google instantly", they are either confused or hoping you are.

Setting it up: the part that silently fails

The mechanics are genuinely simple. You need three things:

A key - any hex string between 8 and 128 characters. Generate it, do not invent it by hand.
That key, as plain text, in a file at the root of your site: https://example.com/.txt, containing nothing but the key.
A POST to https://api.indexnow.org/indexnow with your host, key, key location and URL list.

The failure mode that catches people is ordering. The key file has to be live before you submit anything. IndexNow fetches it to validate the request. If you deploy your application code first and the key file second - which is the natural order if the submission lives in your backend and the key file lives in your frontend - then every submission in between is rejected, and the 202 you got back will have told you nothing was wrong.

On this site the key file is a static file in the frontend's public/ directory and the submission happens in the backend API, which are two separate deployments. I deployed the frontend first on purpose, then checked the file was actually reachable before letting the API send anything:

curl -s -o /dev/null -w "%{http_code}" https://example.com/.txt
200

Thirty seconds of checking that saves you from a silent failure you would not otherwise notice for weeks.

What the request actually looks like

There is no SDK and you do not need one. The entire protocol is one POST with a JSON body:

POST https://api.indexnow.org/indexnow
Content-Type: application/json

{
  "host": "example.com",
  "key": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "keyLocation": "https://example.com/a1b2c3d4e5f60718293a4b5c6d7e8f90.txt",
  "urlList": [
    "https://example.com/blog/my-new-post",
    "https://example.com/blog"
  ]
}

Four fields. keyLocation is technically optional when the file sits at the root under its own name, but send it anyway - it removes any ambiguity about where the engine should look, and costs you nothing.

Two constraints worth knowing before you write the loop: every URL in a single request must belong to the same host, and you can send up to 10,000 of them at a time. If you are backfilling an existing site, read the URLs straight out of your own sitemap rather than querying your database - the sitemap already encodes which pages you consider public, so you inherit that filtering for free.

On a Next.js front end the key file is simply a static file in public/, which means it ships with your normal build and needs no route handler. If your URLs and your publishing logic live in different applications, as they do here, the only thing to remember is that the key file belongs to whichever host serves the pages - not to whichever service makes the call.

Where to call it from

Submit when content actually changes, not on a schedule. On this site the ping is attached to the three admin actions that can make a post publicly visible - create, update and publish - so nothing has to be remembered by hand.

Three conditions are worth enforcing before you send anything, because pointing a crawler at a page it will then be told to ignore wastes the submission and teaches the engine to trust your feed less:

The post is published, not a draft.
It is not scheduled for a future date.
It is not marked noindex.

And make the call best-effort. A search engine being slow or down must never fail an editor's save. Catch everything, log a warning, move on - the sitemap is still there as the slow fallback, which is the entire reason this is an optimisation rather than a dependency.

Don't trust the dashboard either

After my 175 URLs came back 202, I opened Bing Webmaster Tools to watch them arrive. The IndexNow page said:

URLs submitted in last 4 hours: 0

and listed nothing but submissions from April 2025. Hours later it still did.

That is reporting lag, not failure - the protocol-level acceptance and the key validation had both already been confirmed by then. But if the dashboard is the only thing you look at, you will conclude your integration is broken when it is fine, or convince yourself to "fix" something that was never wrong.

Check in this order: the key file returns 200, a single-URL GET returns 200, and only then the dashboard, days later, as a lagging confirmation.

So is it worth it?

Honest answer, and it depends entirely on which problem you have.

Worth it if your content changes and your site has little authority. A site nobody links to gets crawled rarely. Mine had been publishing into a void: the previous version of this site pinged IndexNow through a WordPress plugin until April 2025, then moved to a Next.js stack and nothing replaced it. Eighteen months of posts were never announced to anyone - they just sat in a sitemap waiting for a crawler that had no particular reason to hurry.

Not worth much if you are big. If Bingbot already crawls you hourly, you are telling it something it was about to find out anyway.

Never worth it as a Google strategy, for the reason above.

The real argument for it is the cost side rather than the benefit side. It is one static file, one HTTP call, and perhaps thirty lines of code. There is no ongoing cost, no quota to manage and no account to maintain. Against that, even a modest improvement in how quickly Bing and Yandex notice your work is worth having - particularly now that Bing's index feeds Copilot, which means "how fast does Bing see this page" has quietly become "how fast can an AI assistant cite it". On this site AI assistants already send about as much traffic as Google organic does, so that is not a hypothetical.

What to actually check

If you have IndexNow set up already and have never verified it beyond seeing a 2xx, this takes two minutes:

Fetch your key file. It must return 200 and contain exactly the key, nothing else.
Submit one URL through the GET endpoint and confirm you get 200, not 202.
Confirm your submissions are triggered by content changes, not by a cron job that fires whether anything changed or not.
Confirm drafts and noindexed pages are excluded.

If step two gives you a 202 every time, your key is not validating and nothing you have submitted has counted. That is a quiet, invisible failure that can run for months - which is exactly the kind of bug worth spending two minutes to rule out.

FAQ

What does a 202 response from IndexNow mean?

It means the request was received but your key has not been validated yet - the specification calls it "IndexNow key validation pending". It is not a confirmation. An invalid key returns 202 as well, so a 202 alone tells you nothing about whether your URLs will actually be processed.

Does Google use IndexNow?

No. IndexNow is supported by Bing, Yandex, Seznam and Naver. Google said in 2021 it would evaluate the protocol and has never adopted it for indexing, so you still have to rely on your sitemap and Search Console for Google.

How do I know my IndexNow key is actually working?

Submit a single URL through the GET endpoint rather than a bulk POST. A 200 means the engine fetched your key file and validated it. A 202 means validation is still pending and proves nothing. Bulk submissions return 202 normally, which is why they are no use for verification.

Where does the IndexNow key file go?

At the root of the host whose URLs you are submitting - https://example.com/.txt - containing the key and nothing else. It must be live before you submit anything, because IndexNow fetches it to validate every request.

Is IndexNow worth setting up?

For a site with modest authority that publishes or updates regularly, yes - it costs one static file and about thirty lines of code, with no quota or account to maintain. For a large site already crawled hourly the benefit is small, and it is never a route to faster Google indexing.

Is IndexNow free?

Yes. There is no account, no API key to apply for and no cost. You generate your own key, host it as a text file on your own domain, and submit over plain HTTP.

When should my site submit URLs to IndexNow?

When content actually changes - on publish, update and unpublish - rather than on a schedule. Skip drafts, scheduled posts and anything marked noindex, since submitting a page the crawler will then be told to ignore wastes the submission.

Related on knowledgemarkg.com

Next.js Loads .env.local During Production Builds - And It Overrides .env.production

Kausar Raza — Mon, 02 Nov 2026 07:49:37 GMT

Originally published on knowledgemarkg.com.

A deploy went out. The site loaded, the certificate was valid, the server was in a datacentre in London - and every API call in the browser console was going to http://localhost:5080.

Nothing in .env.production mentioned localhost. The server's own environment did not mention localhost. The value had been welded into the JavaScript bundle at build time, from a file I had forgotten was on my laptop: .env.local.

If you have ever searched "Next.js not reading .env.local", or wondered whether .env.local overrides .env.production, the answer is the one that catches people out:

Next.js loads .env.local during next build, not just next dev - and it outranks .env.production.

The precedence order, and the one line that matters

Next.js merges up to five sources. The first one that defines a variable wins; later sources cannot overwrite it:

process.env                 (real shell / service environment)
.env.$(NODE_ENV).local      (.env.production.local on a prod build)
.env.local                  (skipped ONLY when NODE_ENV=test)
.env.$(NODE_ENV)            (.env.production on a prod build)
.env

Read line three against line four. .env.local sits above .env.production. There is exactly one condition under which Next.js skips it, and it is not "production" - it is NODE_ENV=test.

That single ordering decision is the whole bug. The file most people think of as "my local development overrides" is, during a production build, a higher-priority source than the file literally named for production.

Prove it on your own project in ten lines

You do not have to trust an article about this, and you should not. Next.js publishes its env loader as a standalone package, @next/env - the same code next build calls. You can run it directly.

Three fixture files:

# .env
NEXT_PUBLIC_API_URL=https://api.example.com

# .env.production
NEXT_PUBLIC_API_URL=https://api.prod.example.com

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:5080

And a script that asks the loader what it did:

const { loadEnvConfig } = require('@next/env');
process.env.NODE_ENV = 'production';

const r = loadEnvConfig(process.cwd(), false); // false = not dev
r.loadedEnvFiles.forEach(f => console.log('loaded:', f.path));
console.log('winner:', process.env.NEXT_PUBLIC_API_URL);

On Next.js 16.3.3 that prints:

loaded: .env.local
loaded: .env.production
loaded: .env
winner: http://localhost:5080

A production build, with a .env.production sitting right there, resolving a public API URL to localhost. No warning, no error, exit code 0.

Why NEXT_PUBLIC_ turns a slip into a permanent artifact

Next.js treats two kinds of variable very differently, and the difference decides whether this is a five-second fix or a rebuild.

Server-only variables (no NEXT_PUBLIC_ prefix), read in Server Components, route handlers and other server code, are read from the process environment at runtime.
NEXT_PUBLIC_ variables are inlined at build time. The compiler replaces process.env.NEXT_PUBLIC_API_URL with the literal string and ships it inside the chunk the browser downloads.

So after a bad build, the wrong value is not sitting in config anywhere. It is text inside a .js file:

grep -rl "localhost:5080" .next/static/chunks | head

If that returns anything, no amount of fixing the server's environment will help. This is why the follow-up question is always some version of "I corrected the variable and restarted the app and it still calls localhost". Of course it does. You changed the server; the string is in the browser's download. Only a rebuild moves it.

Why it breaks on your machine and not in CI

This bug has a very specific shape: it follows the person, not the project.

create-next-app adds .env*.local to .gitignore by default. In this repository the ignore rule is even broader - line 35 is just .env*. Which means:

A clean CI checkout has no .env.local. Builds there are correct, every time.
A developer machine has one, because that is what it is for. Builds there silently pick it up.

If your pipeline builds in CI, you may never meet this. If you build locally and ship the artifact - zip the output, upload it through a hosting panel, copy a folder to a VPS - you are exactly the person it happens to. That is how this site shipped it. The build ran on a laptop that had a perfectly reasonable .env.local pointing at a local API, and the resulting zip went to production with that value fossilised inside it.

It is the same class of problem as deploying in the wrong order, which I wrote about in choosing between a Windows and Linux VPS for ASP.NET Core: nothing throws, the artifact is valid, and the mistake only becomes visible to real users.

The fix is a rename, not a rule

The obvious reaction is "delete .env.local before building". That works exactly until the first time somebody forgets, which is to say it does not work.

Rename the file instead:

mv .env.local .env.development.local

Go back to the precedence list. .env.$(NODE_ENV).local is only consulted when NODE_ENV matches, so .env.development.local is invisible to a production build while still beating everything during next dev. Same fixture files, same loader, after the rename:

NODE_ENV=production
  loaded: .env.production, .env
  winner: https://api.prod.example.com

NODE_ENV=development
  loaded: .env.development.local, .env
  winner: http://localhost:5080

Development keeps its overrides. The production build cannot see them even if it wants to. No checklist, no discipline, nothing to remember at 11pm before a deploy - which is the only kind of fix worth having.

What you can still change without rebuilding

Because the two variable types behave differently, "can I change this without a rebuild?" has a clean answer:

Variable	Resolved	Change it by
`NEXT_PUBLIC_*`	Build time, inlined into client JS	Rebuilding. Nothing else.
Everything else, used in server code	Runtime, from the process environment	Updating the service env and restarting.

With output: "standalone" the server reads its environment when the Node process boots, so database connection strings, API keys and third-party secrets really are runtime configuration. You can rotate a key and restart. You cannot rotate a NEXT_PUBLIC_ value that way, ever.

The practical rule: anything the browser can see is a build input, not a config knob. If you genuinely need a browser-visible value to differ per environment without rebuilding, do not reach for an env var - expose it from a small API route and fetch it at runtime. That is a deliberate design decision with a cost, and it is better than discovering the constraint during an incident.

The Docker version of the same trap

Containerised builds hit this twice, and the second one surprises people who thought they had understood the first.

The first is timing. In a Dockerfile, next build runs while the image is being built. Anything you pass at docker run - -e, --env-file, a Compose environment: block, a Kubernetes ConfigMap - arrives long after the bundle was written. Server-side variables are fine, because the server reads them when the process starts. NEXT_PUBLIC_ values are not, so they have to be build arguments:

ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
RUN npm run build

docker build --build-arg NEXT_PUBLIC_API_URL=https://api.example.com .

The practical consequence is one people dislike: a NEXT_PUBLIC_ value that differs between staging and production means two different images. One image promoted through environments cannot carry two different public API URLs. If that matters to you, serve the value from an API route instead and keep the image environment-agnostic.

The second trap is the one that actually bites. .gitignore and .dockerignore are separate files, and the Next.js starter gives you a thorough .gitignore and a thin .dockerignore. So this very ordinary line:

COPY . .

happily copies your local .env.local into the build context, where next build finds it and ranks it above .env.production - exactly as it did on my laptop. You get the localhost bug inside a container that was supposed to be reproducible, and because the file is invisible in Git nobody looking at the repository can see why. Add .env*.local to .dockerignore, or apply the rename and stop worrying about which ignore file is which.

Which env files should actually be committed

Since none of this is obvious from the filenames, here is the whole set in one table:

File	Commit it?	What it is for
`.env`	Usually yes	Defaults shared by every environment. No secrets.
`.env.production`	Yes	Non-secret production values, such as a public API URL.
`.env.development.local`	No	Your personal dev overrides. Invisible to production builds.
`.env.local`	No - and prefer not to have one	Overrides every environment, including production builds.
`.env.example`	Yes	Documentation. Every key, no real values.

Real secrets - database passwords, payment keys, tokens - should not be in any committed file. They belong in the hosting platform's environment settings, where they are read at runtime and can be rotated without a build. The committed files exist to answer "which variables does this app need?", which is what .env.example is for, and the question new developers waste their first morning on.

A sixty-second audit

Worth doing once on any Next.js project you deploy:

ls -a | grep env - list every env file that exists locally. Anything named .env.local or .env.production.local is a live hazard on a local build.
Run the @next/env snippet above with NODE_ENV=production and read which files it loads. Takes five seconds and removes all doubt.
After your next build, grep the output for values that should never reach production: grep -rl "localhost" .next/static/chunks.
Make step 3 a build step rather than a habit. A grep that exits non-zero is a better teammate than a wiki page.

That last point is the general lesson. The staging script for this site asserts that a handful of required files are present before it will produce a deployable folder, because every one of those assertions exists thanks to something that went wrong silently once. Build-time checks are cheap. Finding out from a user that your production site is calling localhost is not.

If you are putting a Next.js front end over an existing .NET backend, the same build-versus- runtime split shapes a lot of the architecture - I went through that in detail in migrating an ASP.NET MVC monolith to a React front end.

FAQ

Does .env.local override .env.production in Next.js?

Yes. Next.js resolves variables in the order process.env, .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV), .env - and the first source that defines a variable wins. Because .env.local is checked before .env.production, a leftover .env.local silently overrides your production values during next build.

Is .env.local loaded during next build, or only next dev?

It is loaded during both. The only time Next.js skips .env.local is when NODE_ENV is test. A production build reads it like any other env file, which is what makes this such a common and quiet failure.

I changed a NEXT_PUBLIC_ variable on the server and restarted. Why is it still the old value?

Because NEXT_PUBLIC_ variables are inlined into the JavaScript bundle at build time. The old value is a literal string inside a file in .next/static/chunks that the browser downloads. Changing the server environment cannot alter a file that was written during the build - only a rebuild can.

Why does the build work correctly in CI but not on my machine?

Because .env*.local is gitignored by default, so it exists on developer machines and never in a clean CI checkout. CI builds get the correct values; local builds pick up the local override. Projects that build locally and upload the artifact are the ones exposed.

Should I just delete .env.local before building?

It works, but it depends on a human remembering every single time. Renaming it to .env.development.local is better: that file is only loaded when NODE_ENV is development, so a production build cannot see it, while next dev still gets your local overrides.

Can I change environment variables at runtime with output: standalone?

For server-side variables, yes - the standalone server reads the process environment when the Node process starts, so you can update a connection string or API key and restart. For NEXT_PUBLIC_ variables, no. Those are fixed at build time regardless of output mode.

Does .env.production.local override .env.local?

Yes. .env.$(NODE_ENV).local is the highest-priority file, above .env.local, which is above .env.production, which is above .env. Only real process environment variables outrank all of them.

Related on knowledgemarkg.com

ChunkLoadError After a Next.js Deploy: Your CDN Cached the HTML

Kausar Raza — Mon, 02 Nov 2026 07:46:19 GMT

Originally published on knowledgemarkg.com.

You deploy. The site comes back with no styling, or half the interactive bits are dead, and the console says:

ChunkLoadError: Loading chunk 478 failed.
(missing: https://example.com/_next/static/chunks/3ivcc6t1s04dh.js)

You check the server. The file is not there — but a file with a different name is, and it contains exactly the code that is missing. Rebuild, redeploy, same thing. Open the site in a private window and it is perfect.

Almost everything written about this error blames the service worker, or webpack's output.publicPath, or tells you to catch the import and retry. On a Next.js site behind a CDN the cause is usually none of those.

Why the chunk name changes every build

Next.js fingerprints its JavaScript. A real filename from this site:

/_next/static/chunks/3ivcc6t1s04dh.js

That name is derived from the file's contents. Change one line of code and the chunk gets a new name, because the point of the hash is that the old URL can be cached forever and never go stale. It is a good design, and it has one consequence people forget: the HTML is the only thing that knows the current chunk names.

Every page ships a