Troubleshooting

Every message below is the literal text Doconut produces, organized by symptom. Find your error, apply the fix.

The viewer shows nothing

Empty viewer area, browser console full of 404s for /doconut-res/... UseDoconutResources() is missing, or placed after UseDoconut(). It must come first in the pipeline.

HTTP 500 with:

Session middleware not configured. Call UseSession() before UseDoconut().

Doconut's token security (on by default) needs ASP.NET session state. Add builder.Services.AddSession() and app.UseSession() before the Doconut middleware branch.

An error image in the page area reading:

You Are Not Authorized To View This Page.

The token was opened by a different browser session. Typical causes: the session cookie isn't reaching the page requests (cross-origin setup, SameSite policy, an API client without a cookie jar), or the app restarted (new session keys). This is the security layer working as designed — see Core Concepts → Sessions & Security.

An error image reading:

Document session not found. Please re-open document.

The token expired (sliding window, default 60 minutes — DocOptions.TimeOut) or the session was closed. Re-open the document for a fresh token.

Opening a document fails

LicenseException with a rejection message — the license file was found but rejected (invalid signature, tampered, blacklisted, or a build outside the license's version/update window). This state blocks opening (fail-fast) rather than degrading to a watermark; read License.RejectionMessage for the reason.

LicenseException:

This document type requires the 'Dicom' plugin license.

The extension is handled only by a plugin (here: DICOM) and the capability is no longer granted. Register the plugin and verify lic.IsCapabilityGranted(LicenseCapability.Dicom). A missing or insufficient non-temporary entitlement normally fails earlier during AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

No viewer — built-in, plugin, or custom — claims that extension. Check the supported-format list; for your own formats, DoconutOptions.RegisterViewer can add one.

InvalidDataException — the file content is corrupt or doesn't match its extension (e.g. a renamed file). Validate uploads before opening.

InvalidOperationException:

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

You resolved DocumentConverter without registering the Converter plugin.

Startup fails

InvalidOperationException mentioning a plugin registered via AddPlugin — the current non-temporary license does not grant that plugin capability. Remove the registration or install a license that grants it. A missing license and a legacy TRIAL file grant no plugin capabilities.

ArgumentException from AddDoconut():

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Fail-fast options validation — fix the offending path.

Build / dependency errors

Compiler error CS1705, or at runtime when opening a document:

Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

Your project pinned System.Text.Json or System.Text.Encodings.Web below the 8.0.x dependencies declared by Doconut.NET6. Remove the downgrade and let NuGet restore the package graph (System.Text.Json 8.0.6 and System.Text.Encodings.Web 8.0.0 in the audited 26.7.0 package).

TypeInitializationException on the first presentation file:

Could not load ... System.Drawing.Common, Version=6.0.0.0

The presentation engine hard-requires System.Drawing.Common 6.0.0 (declared by the package). Don't remove or override that dependency — every PPT/PPTX/PPS/POT/ODP open fails without it.

Output looks wrong

Pages carry a watermark — the app is in an evaluation state: no license file found, an expired temporary or subscription window, or an invalid domain. Inspect IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — the Licensing page's IDoconutLicenseService reference shows a ready-made endpoint.

Legacy documents render garbled text — code-page encodings aren't loaded by default on .NET 6. Add once at startup:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Wrong or substituted fonts on Linux/Docker — the container lacks the document's fonts. Point FontFolders (on WordConfig/PptConfig) at a mounted font directory.

Presentations open but fail to render on Linux/macOS — the current PPT/PPTX/PPS/POT/ODP renderer requires native libgdiplus plus System.Drawing.EnableUnixSupport=true. The package supplies System.Drawing.Common 6.0.0 because that is the last version that honors this switch.

Feature worked in evaluation, silent in production

The classic go-live surprise: an active Temporary license grants every capability; your purchased license grants only what you bought. Search and annotation bundles can disappear when their capabilities are absent. Registered Converter or DICOM plugins with an insufficient non-temporary license fail during AddDoconut(). Compare IsCapabilityGranted(...) against every feature you enable before deployment.

Search finds nothing (or too little)

• For a direct PDF, AllowSearch wasn't enabled at open time. Word, Excel, and PowerPoint expose the same switch through their nested PdfConfig.
• The content is scanned/image-only, so normal Search has no text layer to match. Use a text-bearing source or a PDF projection that preserves text.
• HTML and MS Project (MPP) aren't searchable at their defaults — set DefaultRender = false so they render via a PDF projection with a native text layer. Word, Excel, PowerPoint, TXT, Visio, email, EPUB, and MHT search at their catalog defaults.
• objViewer.CanSearch() is false after initialization — the resolved format has no standard search path. This verdict is separate from the Search license; verify both.

Still stuck?

Isolate the problem against the minimal Quick Start app; if it reproduces there, contact support with the document, your Program.cs, and the license diagnostics output.