Troubleshooting

Diagnose common errors

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:

text
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:

text
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:

text
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:

text
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:

text
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:

text
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():

text
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:

text
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.NET8. Remove the downgrade and let NuGet restore the package graph (System.Text.Json 8.0.5 and System.Text.Encodings.Web 8.0.0).

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 on .NET 8. Add once at startup:

csharp
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. On Linux, see below.

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.

Linux

Opening any document fails with:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Install the font configuration library: apt-get install -y libfontconfig1 (fontconfig on RHEL/Fedora). See Installation.

Opening any document fails with:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

The application references a newer SkiaSharp, directly or through another library. Add SkiaSharp.NativeAssets.Linux at the same version as that SkiaSharp.

Opening any document fails with:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

The host is not a supported platform. Alpine and other musl-based distributions are not supported: use a Debian or Ubuntu based image.

Text is wider or narrower than on Windows, or lines break differently — the document's fonts are not installed, so Doconut uses the closest installed font. Install metric-compatible fonts (fonts-liberation for Arial, Times New Roman and Courier New; fonts-crosextra-carlito and fonts-crosextra-caladea for Calibri and Cambria), or copy your own licensed fonts to /usr/share/fonts/ and run fc-cache -f. Asian text shown as empty boxes needs fonts-noto-cjk.

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.

Was this page helpful?