File Save Errors with Virtual Paths

Updated:June 18, 2026

In ASP.NET applications, PdfDocument.SaveAs() can fail with an error like this:

IronPDF could not write to the file '~/PDFFiles/mydocument.pdf'. It may be open in a PDF viewer.

The message points at a locked file, but the real cause is usually the path. IronPDF writes to disk and needs a fully qualified physical path, while a value like ~/PDFFiles/file.pdf is an ASP.NET virtual path that the file system cannot resolve.

Map the virtual path to a physical path

Convert the virtual path before saving, using Server.MapPath() in ASP.NET Web Forms or HostingEnvironment.MapPath() elsewhere:

string virtualPath = "~/PDFFiles/mydocument.pdf";
string physicalPath = Server.MapPath(virtualPath); // or HostingEnvironment.MapPath outside Web Forms
pdf.SaveAs(physicalPath);

string virtualPath = "~/PDFFiles/mydocument.pdf";
string physicalPath = Server.MapPath(virtualPath); // or HostingEnvironment.MapPath outside Web Forms
pdf.SaveAs(physicalPath);

Imports System.Web

Dim virtualPath As String = "~/PDFFiles/mydocument.pdf"
Dim physicalPath As String = Server.MapPath(virtualPath) ' or HostingEnvironment.MapPath outside Web Forms
pdf.SaveAs(physicalPath)

$vbLabelText $csharpLabel

A minimal working example:

var renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderUrlAsPdf("https://example.com");
string physicalPath = Server.MapPath("~/App_Data/PDFFiles/output.pdf");
pdf.SaveAs(physicalPath);

var renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderUrlAsPdf("https://example.com");
string physicalPath = Server.MapPath("~/App_Data/PDFFiles/output.pdf");
pdf.SaveAs(physicalPath);

Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderUrlAsPdf("https://example.com")
Dim physicalPath As String = Server.MapPath("~/App_Data/PDFFiles/output.pdf")
pdf.SaveAs(physicalPath)

$vbLabelText $csharpLabel

Before you save

Directory exists: create the target folder and confirm the app has write permission to it.
File not open: make sure the output isn't already open in a viewer such as Adobe Reader.
Restricted locations: run with sufficient permissions when writing to protected folders like Program Files.
Verify the path: log the resolved physical path during development to confirm it points where you expect.

WarningAvoid hardcoding drive letters in production; resolve paths at runtime so the app works across environments.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Ready to Get Started?

Nuget Downloads 19,533,604 | Version: 2026.6 just released