Aspose.Words FOSS
.NET
Troubleshooting Aspose.Words FOSS for .NET

Troubleshooting Aspose.Words FOSS for .NET

This page covers common issues encountered when building and using Aspose.Words FOSS for .NET, and how to resolve them.

Build and Installation Issues

dotnet add package Aspose.Words cannot find the package

A NuGet package has not been published yet for this FOSS edition. Run git clone to get the source, then cd into the cloned folder and run dotnet build on the solution:

git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release

Then add a project reference to Aspose.Words.csproj from your own application rather than a package reference.

The project reference does not resolve after cloning

Confirm the reference points at Aspose.Words.csproj inside the cloned Aspose.Words-FOSS-for-.NET/Aspose.Words/ folder, and that the solution built successfully first (dotnet build Aspose.Words.sln -c Release). The library targets .NET Standard 2.0, so any SDK targeting .NET Framework 4.6.2+ or .NET 6/8/10 can reference it.

Loading Issues

UnsupportedFileFormatException when loading a document

UnsupportedFileFormatException is thrown during load when the file format is not recognized or not supported by this edition. This edition’s load formats are DOCX, DOCM, DOTX, DOTM, Flat OPC, Markdown, and plain text — passing an unsupported path such as input.doc to the Document constructor raises this exception instead of returning a loaded document:

using Aspose.Words;

try
{
    Document doc = new Document("input.doc");
}
catch (UnsupportedFileFormatException ex)
{
    Console.WriteLine("Format not supported by this edition: " + ex.Message);
}

Catching UnsupportedFileFormatException around the Document constructor lets you report a clear message instead of letting the exception propagate as a raw stack trace.

FileCorruptedException on a file that looks valid

FileCorruptedException is thrown during load when the file appears corrupted and cannot be parsed — for example, a .docx file that is not a valid ZIP-based OOXML package, or a file truncated during transfer. Re-obtain the file from its source and confirm it opens correctly before loading it with Document.

IncorrectPasswordException when opening a protected document

This is thrown when a document is encrypted with a password and the password supplied to the Document constructor’s LoadOptions overload is missing or incorrect. Supply the correct password through LoadOptions.Password before loading.

Saving and Export Issues

Document.Save() to a PDF, XPS, or image extension fails

This edition does not include the page-layout and rendering subsystem, so Document.Save() cannot export to PDF, XPS, or image formats.

Save to DOCX, DOCM, DOTX, DOTM, Flat OPC, Markdown, or plain text instead — those are the formats this edition actually writes. The commercial Aspose.Words for .NET adds PDF, XPS, and image output.

Page numbers and table-of-contents entries always show 0

Aspose.Words FOSS for .NET includes a full field evaluation engine, so content fields such as DATE and DOCPROPERTY update correctly. Fields that depend on page layout — page numbers, NUMPAGES, and TOC entries — evaluate to a placeholder 0 instead of a computed value, because this edition does not include the layout engine that would normally paginate the document. This is expected behavior in this edition, not a bug.

Digital Signature Issues

Signing a document has no effect

DigitalSignatureUtil.Sign() and the related signing APIs exist in the object model for structural compatibility with the commercial product, but creating a new signature is not functional in this FOSS edition — calling them does not produce a signed output. This edition can inspect and verify signatures already attached to a document through Document.DigitalSignatures and DigitalSignatureUtil.LoadSignatures(), but a signing workflow requires the commercial Aspose.Words for .NET.

Font Issues

Embedded fonts are larger than expected

When EmbedTrueTypeFonts is enabled, fonts are embedded as whole files rather than being subsetted to only the glyphs actually used in the document, so saved files that embed fonts are larger than the equivalent output from the commercial product. There is no workaround in this edition — embedded-font subsetting is not included.

See Also