DEV Community: Kausar Raza

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

Kausar Raza — Tue, 13 Oct 2026 17:55:16 +0000

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.

Originally published on knowledgemarkg.com.

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

Kausar Raza — Tue, 13 Oct 2026 17:51:32 +0000

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:

<aspNetCore processPath="dotnet" arguments=".\YourApi.dll"
            stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout"
            hostingModel="inprocess" />

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:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*"
             modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\YourApi.dll"
                  stdoutLogEnabled="false" hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

One piece of folklore worth correcting: not every section people assume is locked actually is.
On this host <httpErrors> 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.

Originally published on knowledgemarkg.com.

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

Kausar Raza — Tue, 13 Oct 2026 17:49:32 +0000

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:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="iisnode" path="app.js" verb="*" modules="iisnode" />
    </handlers>

    <rewrite>
      <rules>
        <rule name="DynamicContent">
          <match url="/*" />
          <action type="Rewrite" url="app.js" />
        </rule>
      </rules>
    </rewrite>

    <httpErrors existingResponse="PassThrough" />

    <iisnode loggingEnabled="false" devErrorsEnabled="false" />
  </system.webServer>
</configuration>

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 -
<security><requestFiltering> 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: <httpErrors> 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:

<httpErrors existingResponse="PassThrough" />

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:

<iisnode loggingEnabled="true" devErrorsEnabled="true" />

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.

Originally published on knowledgemarkg.com.