Skip to content

Troubleshooting — Deployment

Problems with the IIS host, publishing, and running in production. Background: Deployment.

The site does not start

The application runs in-process under the ASP.NET Core Module. IIS reports a start failure as an HTTP 500 sub-status:

Error Meaning Fix
500.19 — configuration data is invalid IIS does not recognise the aspNetCore handler in web.config: the ASP.NET Core Module is not installed. Install the ASP.NET Core 6.0 Hosting Bundle, then restart IIS.
500.31 — failed to find native dependencies The .NET 6 runtime is missing. The app is published framework-dependent, so the server must supply it. Install the .NET 6 Hosting Bundle (a newer major version does not satisfy a net6.0 app).
500.30 — in-process start failure The application threw during startup. Read the exception — see below.
Browser warns about the certificate, or redirect loop UseHttpsRedirection is on, and outside Development so is HSTS. The site needs an HTTPS binding with a valid certificate. Bind 443 with a proper certificate.

For a 500.30, the exception is in the Windows Application event log. If it is not there, switch on the module's stdout log, reproduce, and read it:

<!-- the web.config generated by dotnet publish, in the site root -->
<aspNetCore processPath="dotnet" arguments=".\NKO.Main.dll"
            stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />

The app-pool identity must be able to write to .\logs. Switch it off again afterwards: the log is never rotated, and the EF console logging on both contexts writes every SQL statement to it — see Logging. The usual startup exceptions are listed under Installation.

The Views/web.config in the repository is a leftover from ASP.NET MVC 5 and is ignored. It is not the site's web.config.

Users are signed out at random

Pattern Cause Fix
Everyone signed out at the same moment; open forms fail with "The antiforgery token could not be decrypted" An app-pool recycle. No Data Protection key location is configured, so unless the pool loads its user profile the keys live in memory and are regenerated on every restart (R4-5). Set Load User Profile = True on the pool.
Individual users, seemingly random More than one worker process — a web garden or farm. Each process has its own keys, so a cookie from one is rejected by another. Maximum worker processes = 1; one server only.
A particular user, right after an admin change Not a sign-out. Permissions are re-read on every request, so removing a group or disabling a login takes effect at once; the user stays signed in with fewer or no keys. Expected.

Background work did not run, or ran twice

All three schedulers run inside the web process, with no durable schedule and no catch-up (R1-3).

Symptom Cause Fix
The 03:00 re-routing did not happen The worker process was not running at 03:00: the idle time-out stopped it, and nothing restarted it. Start mode AlwaysRunning, Idle time-out 0, site Preload enabled True. Then run it by hand at /Admin/TriggerNextUser.
The 03:00 run re-routed only one kind of document Someone ran Refresh Next users for a single type since the last restart; that choice sticks for every later run (R8-11). Recycle the app pool.
No birthday e-mails ScheduledJobsSettings exists but BirthdayGreetingsIsActive is missing — it defaults to off. Or e-mail is disabled (setting row 6). Set the key explicitly; check e-mail.
Birthday e-mails sent twice Two processes: every process runs its own timer. One worker process.
Warehouse exports never finish The Hangfire job failed. There is no dashboard, and Hangfire retries failed jobs automatically. Query the Hangfire database — see Logging.
Loans are never settled automatically LoanJob exists but is never registered (R7-4). No configuration fix.

It broke right after a publish

Symptom Cause
Every PDF export fails The IISProfile publish profile deleted wwwroot\Rotativa\wkhtmltopdf.exe (R4-3). Put it back; publish with extra files kept.
Web Deploy reported "file in use" and the site is half-updated The profile does not take the app offline, and in-process hosting keeps the assemblies locked. Republish with app_offline.htm (the IISProfile1 settings).
Connection or S3 errors that were not there before The publish included a developer's local appsettings.json, overwriting the server's (R4-4). Restore the server's copy, or keep production secrets in environment variables.
Links and e-mails point at the test site The build was made for another environment: URLs are compiled into SiteSettings.cs (R4-4). Build from the right commit for this environment.
Invalid column name … The release's migrations were not applied — see Database.

A release checklist and smoke test are in Build & Publish.

File and folder errors

DirectoryNotFoundException or FileNotFoundException naming a path under C:\upload means the folder or template the feature expects does not exist. Nothing in the application creates these folders (R4-2):

Failing feature Needs
Profile image upload or display C:\upload\nko\files\userImages\
E-signature request form download the file C:\upload\nko\templates\e-sign.pdf
Employee contract export the file C:\upload\nko\templates\contract.xlsx
Asset and stock exports C:\upload\ataa\ware\asset\
Destruction export C:\upload\ware\assetDes\
Destroyed-assets report C:\upload\ware\asset\

The app-pool identity needs read and write on the whole tree. Full list: Server Requirements.

If pages render but navigation, forms or notifications point to the wrong place, check that the site is at the root of its host name. About 130 URLs in the views are root-absolute, and so is the SignalR hub, so the application cannot run as an IIS sub-application such as https://host/erp/. Also check AllowedHosts — see Configuration.