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.

The viewer reports The viewer handler could not be reached (no response). The request never got an answer. A common cause is a BasePath that starts with /: '/doconut' becomes //doconut/DocImage.axd, a request to another host. Write it without the leading slash (BasePath: 'doconut').

The viewer reports Please make sure your middleware is configured. The page endpoint answered 404: UseDoconut() is not mounted where the client's BasePath points. With app.Map("/doconut", branch => branch.UseDoconut()), the client uses BasePath: 'doconut'.

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. Session state needs a cache as well: in a minimal-API app add builder.Services.AddDistributedMemoryCache(), or the app stops at startup with Unable to resolve service for type 'IDistributedCache' (MVC and Razor Pages apps register one already).

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. The refusal is an image served with status 200, so a monitor that checks only status codes counts it as a page.

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:

function ctlDoc_OnViewerBusy() { /* show your busy indicator */ }
function ctlDoc_OnViewerReady() { /* hide it */ }
function ctlDoc_Copy(text) { /* use the copied text */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* report progress */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... your existing options ...
    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). The plugin is registered, but no license grants its capability any more — typically a Temporary license that expired after the app started. Install a license that grants it and verify IsCapabilityGranted(LicenseCapability.Dicom) on IDoconutLicenseService. 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 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 as declared by the 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 license, or an invalid domain. Under an active Temporary license, only plugin output is watermarked. A build released after a paid license's subscription date is not watermarked: opening throws LicenseException. 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 — the server lacks the document's fonts. Install them, or point FontFolders (on WordConfig/PptConfig) at a folder that holds them.

An image annotation shows in the viewer but the export has an "Image blocked" box — the image's host has a private or loopback address, which the server refuses to fetch. See Annotations.

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.
• The page reads the return value of objViewer.Search(...) — the count arrives in its third argument, a callback.

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.