Troubleshooting

Many System.Web failures raise no exception you can see: the page answers an empty 500, an icon 404s, or a request never returns. This page is organized by what you observe. Quoted messages are the literal text Doconut produces.

Symptoms at a glance

Startup failures

An exception thrown in Application_Start does not reach the browser: every request answers an empty 500, and the IIS log shows nothing useful. The exception is in the Windows event log (Event Viewer → Windows Logs → Application, source ASP.NET). The usual ones:

A plugin without its license:

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

The plugin's Doconut.Viewer.<Capability>.lic must be in wwwroot, next to Doconut.Viewer.lic. A missing license and a legacy TRIAL file grant no plugin capabilities.

Invalid options:

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.

An assembly that cannot load. ASP.NET loads every assembly in bin\ when the application starts, so a binding redirect in Web.config that names a version missing from bin\ stops the whole site. Copy the redirects NuGet generated (for an SDK-style project, from bin\<YourApp>.dll.config) instead of editing them by hand, and copy them again after package updates.

You Are Not Authorized To View This Page.

The page is refused because the requesting ASP.NET session was never granted the document. Check, in order:

1. The open ran with session state. MVC controllers and Web Forms pages have it. A custom IHttpHandler that opens documents must implement System.Web.SessionState.IRequiresSessionState, or it has no session to grant.
2. Session state is on. <sessionState mode="Off" /> refuses every page.
3. The cookie reaches the handler. The widget's same-origin requests carry ASP.NET_SessionId; a script, a server-to-server call, or a cross-origin page without cookies does not.
4. Web farm: the open bound the browser (DocOptions.BrowserId) and the page passes the ticket (objViewer.View(token, access)); every node uses the same signing key.

The refusal is an image served with status 200, about 2 KB. A monitor that checks only status codes counts it as a page.

Document session not found. Please re-open document.

The token expired (sliding window, DocOptions.TimeOut, default 60 minutes), the document was closed, or — on a single server — the application pool recycled. A recycle happens on schedule, on every Web.config edit, and after the pool's idle time-out (20 minutes by default in IIS). Open the document again for a new token.

Opening a document fails

LicenseException with a rejection reason — the license file was found but rejected (invalid signature, tampering, blacklisting, or a build outside the license's version window). Opening is blocked rather than watermarked.

LicenseException:

This document type requires the 'Dicom' plugin license.

The extension is handled only by a plugin (here DICOM) whose capability is not granted.

FormatNotSupportedException — no viewer (built-in, plugin, or custom) claims the extension. DoconutOptions.RegisterViewer can add one for your own formats.

InvalidDataException — the content is corrupt or does not match its extension (a renamed file). Validate uploads before opening.

InvalidOperationException:

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

DocumentConverter was resolved without registering the Converter plugin.

Output looks wrong

Pages carry a watermark — no license was found, or it has expired or does not cover this version. Under IIS, the license must be in wwwroot under the site root (AppContext.BaseDirectory\wwwroot), not in bin\. Check IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

Legacy documents render garbled text — register the code-page encodings once, at startup:

// Global.asax.cs, Application_Start - before DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Wrong or substituted fonts — the server lacks the document's fonts. A Windows Server without Office has far fewer fonts than a development machine. Install the fonts, or point FontFolders (on WordConfig and 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

An active Temporary license grants every capability; your purchased license grants only what you bought. Without a capability, its Search or Annotation files are not emitted, and a registered plugin stops the site at startup. Compare IsCapabilityGranted(...) with every feature you use before deploying.

Search finds nothing (or too little)

• For a PDF, AllowSearch was not enabled when the document was opened — it defaults to false. Word, Excel, and PowerPoint expose the same switch.
• The content is scanned or image-only, so there is no text layer to match.
• HTML and Microsoft Project (MPP) are not searchable at their defaults: set DefaultRender = false so they render through a PDF projection with text.
• objViewer.CanSearch() is false after initialization: the resolved format has no search path. This is separate from the Search license; check both.
• The page reads the return value of objViewer.Search(...) — the count arrives in its third argument, a callback.

Still stuck?

Reproduce the problem with the minimal setup from Quick Start. If it reproduces there, contact support with the document, your Global.asax.cs, the Doconut parts of Web.config, and the Windows event log entry if there is one.