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.

The server is fine but the page misbehaves — with no error anywhere

These are the failure modes to suspect first after carrying an application forward. All three leave the server working perfectly, render the document correctly, and report nothing in the browser console.

A busy spinner that never stops. Your viewer callbacks are declared as global functions named after the container id — ctlDoc_OnViewerReady() and friends. The previous viewer looked those names up; this one does not. The handler that would have hidden the spinner simply never runs. Pass the functions as options instead:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

The document behind the spinner is fine. The full option list is in ViewerConfig.

Missing viewer icons or chrome, pages otherwise correct. ResPath is empty or points at the application root — correct in the previous library, wrong here. It must name the prefix that UseDoconutResources() mounts:

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

Broken tiles for later pages when serving from shared storage. Pages that are still being written answer 202 Accepted. A client without retryOn409: true treats that as a failed image. See Distributed Deployments.

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

The package will not install at all — Doconut.NETStandard 26.8.0 targets netstandard2.1, so NuGet refuses a .NET Framework project. This is not a resolvable restore error: .NET Framework cannot consume netstandard2.1. Use the Doconut.NETFramework package instead.

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

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

Your project pinned System.Text.Json or System.Text.Encodings.Web below the 9.0.x dependencies declared by Doconut.NETStandard. Remove the downgrade and let NuGet restore the package graph (System.Text.Json 9.0.0 and System.Text.Encodings.Web 9.0.0 in the audited 26.8.0 package).

A wall of compile errors immediately after bumping the package — this is expected. 26.8.0 is a different API surface from 26.7.0, not a compatible update. Most of the errors are the using lines that moved to the root Doconut namespace; work through Migrate to .NET Standard 2.1 rather than patching them one by one.

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. 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.