Dépannage

Chaque message ci‑dessous est le texte littéral produit par Doconut, organisé par symptôme. Trouvez votre erreur, appliquez la correction.

Le visualiseur n'affiche rien

Zone de visualisation vide, console du navigateur remplie de 404 pour /doconut-res/...
UseDoconutResources() est manquant, ou placé après UseDoconut(). Il doit être le premier dans le pipeline.

HTTP 500 avec :

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

La sécurité des jetons de Doconut (activée par défaut) nécessite l'état de session ASP.NET. Ajoutez builder.Services.AddSession() et app.UseSession() avant la branche middleware de Doconut. L'état de session nécessite également un cache : dans une application minimal‑API ajoutez builder.Services.AddDistributedMemoryCache(), ou l'application s'arrête au démarrage avec Unable to resolve service for type 'IDistributedCache' (les applications MVC et Razor Pages en enregistrent déjà un).

Une image d'erreur dans la zone de la page affichant :

You Are Not Authorized To View This Page.

Le jeton a été ouvert par une session de navigateur différente. Causes typiques : le cookie de session n'atteint pas les requêtes de la page (configuration cross‑origin, politique SameSite, un client API sans jar de cookies), ou l'application a redémarré (nouvelles clés de session). Il s'agit de la couche de sécurité qui fonctionne comme prévu — voir Concepts de base → Sessions & Sécurité.

Une image d'erreur affichant :

Document session not found. Please re-open document.

Le jeton a expiré (fenêtre glissante, 60 minutes par défaut — DocOptions.TimeOut) ou la session a été fermée. Rouvrez le document pour obtenir un nouveau jeton.

L'ouverture d'un document échoue

LicenseException avec un message de rejet — le fichier de licence a été trouvé mais rejeté (signature invalide, altéré, sur liste noire, ou une version hors de la fenêtre de version/mise à jour de la licence). Cet état bloque l'ouverture (fail‑fast) plutôt que de la dégrader en filigrane ; lisez License.RejectionMessage pour la raison.

LicenseException :

This document type requires the 'Dicom' plugin license.

L'extension n'est gérée que par un plugin (ici : DICOM) et la capacité n'est plus accordée. Enregistrez le plugin et vérifiez lic.IsCapabilityGranted(LicenseCapability.Dicom). Un droit non temporaire manquant ou insuffisant échoue généralement plus tôt pendant AddDoconut().

FormatNotSupportedException :

Document format '<extension>' is not supported.

Aucun visualiseur — intégré, plugin ou personnalisé — ne prend en charge cette extension. Vérifiez la liste des formats pris en charge ; pour vos propres formats, DoconutOptions.RegisterViewer peut en ajouter un.

InvalidDataException — le contenu du fichier est corrompu ou ne correspond pas à son extension (par ex. un fichier renommé). Validez les téléchargements avant l'ouverture.

InvalidOperationException :

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

Vous avez résolu DocumentConverter sans enregistrer le plugin Converter.

Le démarrage échoue

InvalidOperationException mentionnant un plugin enregistré via AddPlugin — la licence non temporaire actuelle n'accorde pas cette capacité de plugin. Supprimez l'enregistrement ou installez une licence qui l'accorde. Une licence manquante et un fichier legacy TRIAL n'accordent aucune capacité de plugin.

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

Validation des options fail‑fast — corrigez le chemin incriminé.

Erreurs de compilation / dépendances

Erreur de compilation CS1705, ou à l'exécution lors de l'ouverture d'un document :

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

Votre projet a épinglé System.Text.Json / System.Text.Encodings.Web en dessous de 10.0.x. Supprimez le rétrogradage et laissez NuGet restaurer les versions déclarées par Doconut.NET8.

TypeInitializationException sur le premier fichier de présentation :

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

Le moteur de présentation exige strictement System.Drawing.Common 6.0.0 (déclaré par le paquet). Ne supprimez pas ou ne remplacez pas cette dépendance — toute ouverture de PPT/PPTX/PPS/POT/ODP échoue sans elle.

Le rendu est incorrect

Les pages portent un filigrane — l'application est en état d'évaluation : aucun fichier de licence trouvé, une fenêtre temporaire ou d'abonnement expirée, ou un domaine invalide. Inspectez IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la référence IDoconutLicenseService de la page de licence indique un point de terminaison prêt à l'emploi.

Les documents legacy affichent du texte illisible — les encodages de pages de code ne sont pas chargés par défaut sur .NET 8. Ajoutez-les une fois au démarrage :

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Polices incorrectes ou substituées sur Linux/Docker — le conteneur ne possède pas les polices du document. Pointez FontFolders (sur WordConfig/PptConfig) vers un répertoire de polices monté.

Les présentations s'ouvrent mais ne s'affichent pas sur Linux/macOS — le rendu actuel PPT/PPTX/PPS/POT/ODP nécessite libgdiplus natif plus System.Drawing.EnableUnixSupport=true. Le paquet fournit System.Drawing.Common 6.0.0 car c'est la dernière version qui respecte ce basculement.

Fonctionnalité fonctionnant en évaluation, silencieuse en production

La surprise classique du passage en production : une licence Temporaire active accorde toutes les capacités ; votre licence achetée n'accorde que ce que vous avez acheté. Les ensembles de recherche et d'annotation peuvent disparaître lorsque leurs capacités sont absentes. Les plugins Converter ou DICOM enregistrés avec une licence non temporaire insuffisante échouent pendant AddDoconut(). Comparez IsCapabilityGranted(...) à chaque fonctionnalité que vous activez avant le déploiement.

La recherche ne trouve rien (ou trop peu)

• Pour un PDF direct, AllowSearch n'était pas activé lors de l'ouverture. Word, Excel et PowerPoint exposent le même commutateur via leurs PdfConfig imbriqués.
• Le contenu est scanné/uniquement image, donc la Recherche normale n'a aucune couche de texte à faire correspondre. Utilisez une source contenant du texte ou une projection PDF qui préserve le texte.
• HTML et MS Project (MPP) ne sont pas recherchables par défaut — définissez DefaultRender = false afin qu'ils se rendent via une projection PDF avec une couche de texte native. Word, Excel, PowerPoint, TXT, Visio, email, EPUB et MHT sont recherchables avec leurs paramètres de catalogue par défaut.
• objViewer.CanSearch() est false après l'initialisation — le format résolu n'a aucun chemin de recherche standard. Ce verdict est distinct de la licence de Recherche ; vérifiez les deux.

Toujours bloqué ?

Isolez le problème avec l'application Quick Start minimale ; s'il se reproduit, contactez le support avec le document, votre Program.cs, et la sortie de diagnostic de licence.