Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsShort answer: when the exception says Parameter name: controllerContext, the failure occurs before wkhtmltopdf renders anything. Rotativa asked ASP.NET MVC for a view without the request context that identifies the controller, routes, view engines and HTTP request. Return ActionAsPdf or ViewAsPdf from a normal MVC action, then check the view, model and route. Only after that should you troubleshoot cookies, JavaScript, local files or the wkhtmltopdf process.
Other parameter names point to different faults. Preserve the full exception and the first application frame; it tells you whether MVC is missing an HttpContext, model, route value, view or controller context.
What the exception actually means
A typical stack trace for this problem ends in ViewEngineCollection.FindView, then Rotativa.ViewAsPdf.GetView, CallTheDriver and AsResultBase.BuildFile. That sequence matters: Rotativa is trying to turn an MVC view into HTML, but MVC has not received a valid ControllerContext. wkhtmltopdf has not yet been given a page to convert.
The MVC resource messages distinguish several cases:
#1 Best Overall
controllerContext: the view lookup was invoked without the request context.HttpContext: the HTTP context itself is missing.- A model-item message: the view requires a non-null model, but the action passed
null. - A route message: no route matches the supplied values, or the matched route has no
controllervalue. - A view-not-found message: MVC searched the expected locations and could not find the view.
Do not treat all “Value cannot be null” exceptions as a wkhtmltopdf installation problem. The parameter name and the first frame in your own application are the quickest way to select the right repair.
Repair it in the right order
- Read the parameter name and first application frame. Copy the complete exception, including the inner exception and stack trace. Start with the named value rather than changing converter flags at random.
- Generate the PDF from a real MVC request. Put PDF construction inside a controller action that owns a valid context. Rotativa’s documented patterns are
ActionAsPdffor another action andViewAsPdffor a view and model. - Check the view and model. Confirm that the file exists in the MVC search locations, its declared model type matches the object supplied by the action, and required data is not null.
- Check routing and the target URL. Register routes before the action runs. For URL-based conversion, verify scheme, host, port, area, action, controller and route values from the machine that runs wkhtmltopdf.
- Separate MVC rendering from conversion. Capture the final HTML or URL and request it directly from the converter host. If MVC cannot render it, wkhtmltopdf options cannot fix it.
- Make authentication and browser behavior explicit. Supply cookies or headers, wait for client-side rendering, and handle local assets deliberately.
- Check deployment. Use an absolute executable path, verify the IIS or application-pool identity can execute it and access temporary/output directories, and record stderr and the exit code.
Use a controller action that has a context
Call another action with ActionAsPdf
This pattern lets Rotativa execute a normal MVC action and use the context created for that request:
public ActionResult PrintIndex()
{
return new ActionAsPdf("Index", new { name = "Giorgio" })
{
FileName = "Test.pdf"
};
}The Index action must be routable and must return a view that can render without missing data. If it requires authentication, the converter must receive an authenticated session or the action must be intentionally public.
Render a view and a non-null model with ViewAsPdf
public ActionResult Invoice(int id)
{
var model = repository.GetInvoice(id);
if (model == null) return HttpNotFound();
return new ViewAsPdf("Invoice", model)
{
FileName = "invoice.pdf"
};
}Use the overload that names the view when the action’s default view is not the one you want. The model instance must satisfy the view’s @model declaration. Returning HttpNotFound() (or another deliberate response) is safer than allowing a null model to reach a view that requires one.
Why BuildFile often fails in a static or background path
BuildFile() needs the same information Rotativa obtains during an MVC request: an HTTP context, controller, route data, view engines and request services. A static helper, scheduled job or arbitrary background thread normally has none of these. Calling it there can produce a null controllerContext even though the same PDF works from a browser request.
The practical fix is to expose a protected MVC action and invoke it through a controlled request, or to deliberately construct a complete equivalent request context. The latter is easy to get wrong and should be reserved for code that controls routing, URL generation, dependencies and lifetime. Do not “fix” the exception by passing a half-populated context.
Validate the view, model and MVC search path
View location
For a conventional controller, check Views/ControllerName/ViewName.cshtml. Areas add an area-specific search path. A renamed action, misspelled view name or deployment that omitted the .cshtml file produces a view-not-found error after the context problem is fixed. Test the same action in the deployed application, not only in Visual Studio.
Model contract
Compare the view’s declared model type with the object passed to ViewAsPdf or returned by the action. A null model is a separate MVC failure; the framework reports that the dictionary requires a non-null model item of a particular type. Fix the repository query, handle a missing record, or make the view’s model optional only when that is genuinely valid.
Free tools Windows power users keep installed
One-click scans. No signup required.
Nested data and partials
A top-level model can be non-null while a partial view, editor template or layout dereferences a null child property. Render the action as HTML first and inspect the inner exception. Resolve missing navigation data and layout dependencies before invoking Rotativa.
Check routes and URL-based conversion
When using UrlAsPdf or RouteAsPdf, write down the exact URL the converter will request. It must identify the intended protocol, host, port, virtual directory, area, controller, action and route values. A route table that matches a browser request on your development machine may produce a different URL behind IIS, a reverse proxy or a load balancer.
- Register routes before the application starts handling requests.
- Ensure the matched route contains a
controllervalue; MVC explicitly reports when it does not. - Supply every required identifier, such as an invoice ID or slug.
- Use the externally reachable host and scheme when wkhtmltopdf runs in another process or server.
- Do not assume
localhostin a container, IIS worker process or remote conversion service refers to your web application.
Log the final URL, status code and response length. Request that URL from the same machine and identity that launches wkhtmltopdf. A 302 to a login page, a 404 caused by a missing virtual directory or a certificate error is a URL/authentication problem, not a view-engine problem.
Separate MVC errors from wkhtmltopdf errors
First make the action return correct HTML in a normal browser request. Then test the converter against that URL or an exported HTML file. This boundary prevents two different failures from being mixed together:
Recommended Free Tools
- MVC/Rotativa stage: null context, missing route, missing view or invalid model. The fix is in controller code, routing or view data.
- Converter stage: authentication, JavaScript timing, blocked resources, local-file policy, network failures or process permissions. The fix is in the request and wkhtmltopdf configuration.
wkhtmltopdf 0.12.6 (the patched-Qt build documented by the project manual) accepts URL or file page objects. It has explicit controls for cookies, custom headers, JavaScript delay, load-error handling and local-file access. Use those only after the MVC action renders successfully.
Options that solve common converter-stage failures
| Symptom | Relevant control | What to verify |
|---|---|---|
| Login page or missing user data | --cookie, --cookie-jar, --custom-header |
Cookie names, values, domain/path and required authorization headers are valid for the target host. |
| Charts or client-rendered fields are absent | --javascript-delay |
The delay is long enough for the page’s rendering work; inspect the page for JavaScript errors. |
| One failed resource aborts output | --load-error-handling |
Choose a policy deliberately and log which resource failed instead of hiding a broken document. |
| Images, fonts or CSS use local paths | --allow <path>, or --enable-local-file-access |
The process can read only the directories it needs. Local-file access is disabled by default in the documented build. |
| Input is not an HTTP page | URL or file page object | The file exists on the converter host and all relative asset paths resolve from its location. |
For example, a diagnostic command can make the request details visible while you test:
wkhtmltopdf
--cookie sessionid YOUR_SESSION_VALUE
--custom-header Authorization "Bearer YOUR_TOKEN"
--javascript-delay 1500
--load-error-handling skip
https://app.example.com/Invoices/123
invoice-123.pdfUse real credentials only in a protected test environment. Never print session cookies or authorization headers into ordinary production logs.
Deployment checks that are easy to miss
Executable and process identity
Configure an absolute path to the wkhtmltopdf executable. The path available to an interactive administrator may not exist for an IIS application-pool identity. Confirm that identity can execute the binary and read any fonts, templates and local asset directories.
Temporary and output directories
Rotativa and the converter may create temporary files before returning the response. Verify write permission to the configured temporary location and the final output directory, check available disk space, and clean up abandoned files. Capture standard error and the process exit code; a missing executable and a rendering failure should not look like the same exception.
Network and TLS
If the application requires an internal DNS name, proxy or trusted certificate, test from the converter’s environment. A page that loads in your desktop browser can still time out or fail certificate validation on the server.
Troubleshooting by symptom
| Observed error or result | Likely cause | Action |
|---|---|---|
Value cannot be null. Parameter name: controllerContext |
Rotativa was called outside a complete MVC request. | Return ActionAsPdf or ViewAsPdf from a controller action; avoid static BuildFile() calls. |
| “The model item passed into the dictionary is null…” | The action supplied no model where the view requires one. | Check the repository result, return a deliberate 404 for a missing record, and pass the correct model type. |
| “No route in the route table matches…” | Route values, area or URL are wrong. | Log and request the final URL from the converter host; fix route registration or supplied values. |
| “The matched route does not include a ‘controller’ route value” | The selected route cannot identify a controller. | Use a route with a controller segment/value or supply the correct route name and values. |
| View-not-found exception | Wrong view name, folder, area or deployment package. | Confirm the deployed file and the MVC search locations; specify the view explicitly when needed. |
| PDF contains a login page | Authentication was not sent to wkhtmltopdf. | Provide the required cookie or custom header and verify redirects from the converter host. |
| PDF is blank or missing dynamic content | JavaScript has not finished, or a script failed. | Inspect the HTML response, fix script errors and add an appropriate JavaScript delay. |
| Images or CSS are missing | Relative URLs, inaccessible hostnames or local-file restrictions. | Use absolute reachable URLs, check permissions and grant only the required path with --allow or explicitly enable local access. |
| Process cannot start or exits immediately | Wrong executable path, identity permission or temporary-directory access. | Use an absolute path, test under the application identity, capture stderr and check the exit code. |
Self-hosted wkhtmltopdf versus a hosted converter
The right ownership model depends on where your pages and credentials can safely be processed.
| Decision axis | Self-hosted wkhtmltopdf with Rotativa | Hosted conversion API |
|---|---|---|
| Request-context fidelity | You control the MVC action and can preserve its exact route and view context. | You submit a URL or HTML and must make authentication and network access available to the service. |
| Cookies and headers | Configured in your process and infrastructure. | Supported only to the extent of the provider’s request options and security model. |
| Assets and JavaScript | Local files, delays and browser behavior are your responsibility. | The service’s browser environment and network reachability determine the result. |
| Observability | You can collect process stderr, exit codes and server logs directly. | You depend on API responses, job status and provider diagnostics. |
| Operational ownership | You patch, deploy, scale and secure the executable. | You outsource converter operations but must review data handling and availability terms. |
Rotativa documentation also describes a hosted Rotativa PDF API as an HTTP/Azure alternative for teams that cannot safely run the converter locally. Confirm the current service behavior, security terms and availability before moving sensitive documents.
Or skip the browser setup
If your requirement is a clean capture of an MVC page, ScreenshotNeo can take the page directly instead of making you install and supervise a browser process. It accepts a URL and can return PNG, JPEG, WebP or PDF. Before capture it accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For a page that is reachable from the ScreenshotNeo service, the one-call forms are:
ScreenshotNeo API documentation
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://app.example.com/Invoices/123 -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://app.example.com/Invoices/123"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://app.example.com/Invoices/123' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also supports custom headers and cookies for protected pages, waits for a selector, delay or network idle, full-page lazy-image loading, CSS-selector element capture, device presets, custom viewports, retina scale, JavaScript and CSS, request blocking, timezone and geolocation, resizing, caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an MCP server with take_screenshot, get_page_info and capture_pdf for AI clients such as Claude and Cursor.
The free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account to try it without a card.
Frequently Asked Questions
Can I call Rotativa from a scheduled job at all?
Yes, but not by assuming a background thread has MVC state. Run a deliberate HTTP request to a protected rendering action, or build and maintain a complete request context yourself; the normal controller-action pattern is less fragile.
Should I enable local-file access globally to fix missing images?
No. Prefer absolute HTTP(S) asset URLs or grant only the required directory with --allow. Enable broader local access only when you understand which files the converter can read.
What should I archive when a PDF fails in production?
Record the exception parameter name and stack trace, final URL or input file, converter stderr, exit code, executable path, response status and the relevant route/model identifiers. Redact cookies, authorization headers and personal document data.
The Bottom Line
A null controllerContext is a Rotativa/MVC invocation failure. Generate the PDF from a real MVC action, make the view, model and route valid, then diagnose authentication, JavaScript, assets and process permissions at the wkhtmltopdf stage.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
