ScreenshotNeo

BlogHow-to

How to Fix Rotativa in an ASP.NET Core 1.0 Application

Resolve Rotativa failures in ASP.NET Core 1.0 by checking package compatibility, wkhtmltopdf paths, Startup setup, permissions, and deployment.

By the ScreenshotNeo team30 September 20267 min read

How to Fix Rotativa in an ASP.NET Core 1.0 Application

Direct answer: first verify that your Rotativa package can target ASP.NET Core 1.0. The current Rotativa.AspNetCore package advertises support for .NET Core 3.1 through .NET 8, and its current source does not show an ASP.NET Core 1.0 branch. If your application is truly ASP.NET Core 1.0, a current package may not compile or run. Use a historically compatible package, upgrade the application, or move PDF generation to a hosted service.

When the package is compatible, most runtime failures come from the native wkhtmltopdf executable. Rotativa renders a Razor view to HTML and invokes that executable. The executable directory must exist and be readable and executable by the web process.

1. Confirm the framework and package before changing paths

Open the project file or legacy project.json and record both the target framework and Rotativa version.

{
  "frameworks": {
    "netcoreapp1.0": {
      "dependencies": {
        "Microsoft.AspNetCore.Mvc": "1.0.0",
        "Rotativa.AspNetCore": "YOUR_COMPATIBLE_VERSION"
      }
    }
  }
}

Do not assume that Rotativa.AspNetCore 1.4.0 supports this target. The historical 1.2.0-beta package required Microsoft.AspNetCore.Mvc 2.0.1 or newer under .NET Standard 2.0, which also does not make it an ASP.NET Core 1.0 package. Check the exact package metadata and your dependency graph. If no package version targets your framework, stop debugging deployment paths and choose an upgrade or hosted alternative.

2. Install the native wkhtmltopdf binary

Rotativa is a wrapper; it does not replace the native converter. Obtain a build appropriate for the operating system used in deployment and place the executable in a directory that will be deployed with the application.

Rotativa renders a Razor view and delegates conversion to the native wkhtmltopdf executable.
Rotativa renders a Razor view and delegates conversion to the native wkhtmltopdf executable.
  • Windows: the file must be named wkhtmltopdf.exe.
  • Linux, macOS and other non-Windows hosts: the driver looks for wkhtmltopdf.
  • The directory must be present in the published output, not only in your source checkout.
  • On Unix-like systems, mark the file executable and install any native libraries required by the binary.

A conventional layout is:

MyApp/
  Rotativa/
    wkhtmltopdf.exe       # Windows
    wkhtmltopdf            # non-Windows
  Views/
  wwwroot/

3. Configure Rotativa in Startup

Call RotativaConfiguration.Setup before requests are served. Pass the application root and the relative directory containing the executable. Setup validates the directory and throws an ApplicationException that includes the path it searched when the directory is missing.

using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Rotativa.AspNetCore;

public class Startup
{
    private readonly IHostingEnvironment _environment;

    public Startup(IHostingEnvironment environment)
    {
        _environment = environment;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
    }

    public void Configure(IApplicationBuilder app)
    {
        // The first argument is the deployed application root.
        // The second is relative to that root.
        RotativaConfiguration.Setup(_environment.ContentRootPath, "Rotativa");

        app.UseMvc(routes =>
        {
            routes.MapRoute(
                name: "default",
                template: "{controller=Home}/{action=Index}/{id?}");
        });
    }
}

Some ASP.NET Core 1.0 templates expose IHostingEnvironment.WebRootPath and ContentRootPath differently. Use the path that actually contains the deployed Rotativa directory. Do not point to your repository root when the process runs from a publish directory or service directory.

4. Return a ViewAsPdf result

Rotativa only runs when the action returns its PDF result. A normal View() response renders HTML in the browser.

using Microsoft.AspNetCore.Mvc;
using Rotativa.AspNetCore;

public class ReportsController : Controller
{
    public IActionResult Invoice(int id)
    {
        var model = LoadInvoice(id);
        return new ViewAsPdf("Invoice", model)
        {
            FileName = "invoice-" + id + ".pdf"
        };
    }

    private object LoadInvoice(int id)
    {
        // Replace with your data access code.
        return new { Id = id, Total = 125.00m };
    }
}

The view can use normal Razor markup and a model. The driver renders that view to HTML, then passes the HTML and conversion switches to wkhtmltopdf. The README also documents view data, partial views, disabling the injected base URL, custom switches, inline versus attachment disposition, and BuildFile for obtaining bytes.

5. Verify the deployed process, not just the source tree

  1. Publish the application.
  2. Inspect the publish directory and confirm the configured relative directory exists.
  3. Confirm the expected executable name for the operating system.
  4. Run the application under the same account used by IIS, systemd, Docker or your hosting platform.
  5. Check read and execute permissions on the directory and binary.
  6. On Linux, verify executable-bit and native runtime dependencies.
  7. Request the PDF endpoint and record the complete exception, including the searched path.

“Works locally” usually means the development machine has a different current directory, permissions, operating system, or native dependency set than production.

The deployed process must be able to find, read and execute the configured binary.
The deployed process must be able to find, read and execute the configured binary.

6. Troubleshooting common errors

Symptom Likely cause Fix
Package will not restore or compile The selected Rotativa package does not target ASP.NET Core 1.0. Inspect package targets and dependencies. Use a compatible historical build, upgrade the framework, or use a hosted API.
“Folder … does not exist” or Setup throws ApplicationException The relative directory is absent from the deployed root, or the wrong root path was supplied. Deploy Rotativa beside the application and pass the actual ContentRootPath.
wkhtmltopdf not found Wrong executable name, missing file, or a path outside the published output. Use wkhtmltopdf.exe on Windows and wkhtmltopdf elsewhere; inspect the running host.
Permission denied The web-process identity cannot read or execute the binary. Grant directory read and execute permissions to that identity. On Unix, set the executable bit.
Empty or partially rendered PDF The view depends on browser JavaScript, relative assets, authentication, or external resources unavailable to the converter. Use absolute or correctly injected base URLs, ensure assets are reachable by the server process, and simplify or wait for client-only content.
Fails only after deployment Different OS, working directory, permissions, native libraries, or publish layout. Repeat the checks from the deployed process account and log the resolved root and Rotativa directory.
Action returns HTML instead of PDF The controller returns View() rather than ViewAsPdf. Return new ViewAsPdf() with the view name and model.

7. Rendering options and edge cases

  • Named views and models: pass a view name and model when the action is not mapped to the expected Razor view.
  • Partial views: render a partial as part of a dedicated PDF view so layout and asset paths are predictable.
  • Base URL: Rotativa can inject a base URL for relative links; disable that behavior only when your markup supplies its own correct base.
  • Custom switches: use documented wkhtmltopdf switches for page size, margins, orientation and headers or footers. Validate switches against the binary version installed on the server.
  • Disposition: choose inline display or attachment download according to your response requirements.
  • BuildFile: use it when application code must receive PDF bytes for storage or another response.
  • Authentication: a converter process may not share the browser session. Make required resources accessible to the server process or provide appropriate request configuration.

8. Performance, reliability and cost considerations

Each conversion starts a native process and renders a full page, so PDF generation is more expensive than returning HTML. Keep views focused, avoid unnecessary remote assets, and do not generate large batches inside a synchronous web request without measuring timeout behavior. For repeatable output, pin the wkhtmltopdf build and keep the same fonts and native libraries across environments.

Protect endpoints from unbounded user input and concurrent conversion spikes. Queue long jobs when your hosting model permits it, persist failures with the input identifier, and return a retryable status to callers. Rotativa itself does not remove the need to monitor process failures, timeouts and disk usage.

9. Upgrade or use a hosted PDF service

If no Rotativa package supports ASP.NET Core 1.0, upgrading the application is the maintainable local solution. If an upgrade is not practical, a hosted HTTP service can keep native PDF tooling out of the legacy process. A 2017 Rotativa.io vendor article describes an Azure service for ASP.NET Core PDF generation, but the supplied research does not establish its current pricing or availability; verify those details before adopting it.

Or skip the browser setup

For screenshot or PDF capture without installing a browser executable, ScreenshotNeo provides a website capture API and MCP server. It removes cookie banners, newsletter popups and chat widgets before capture; bot checks, blank pages and failed loads are never billed. Its MCP server lets Claude, Cursor and other MCP clients take screenshots, and the free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Create a free ScreenshotNeo account for 1,000 screenshots each month with no card.

FAQ

Does Rotativa.AspNetCore support ASP.NET Core 1.0?

Current documentation advertises .NET Core 3.1 through .NET 8. Compatibility with ASP.NET Core 1.0 cannot be assumed; verify the exact package targets.

Where should wkhtmltopdf be installed?

Place the operating-system-specific executable in the directory supplied to RotativaConfiguration.Setup, relative to the deployed application root.

Why does Setup fail only in production?

Production commonly uses a different root path, process identity, publish layout, operating system or native dependency set. Inspect the deployed directory and permissions under the real service account.

Can I keep the legacy application without installing wkhtmltopdf?

Use a hosted PDF service or upgrade to a supported local rendering stack. Confirm current availability and pricing with the provider.