Dépannage
Diagnostiquer les erreurs courantes
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.
Le visualiseur signale The viewer handler could not be reached (no response).
La requête n’a jamais reçu de réponse. Une cause fréquente est un BasePath qui commence par / : '/doconut' devient //doconut/DocImage.axd, une requête vers un autre hôte. Écrivez‑le sans la barre oblique initiale (BasePath: 'doconut').
Le visualiseur signale Please make sure your middleware is configured.
Le point de terminaison de la page a répondu 404 : UseDoconut() n’est pas monté à l’endroit où le BasePath du client pointe. Avec app.Map("/doconut", branch => branch.UseDoconut()), le client utilise BasePath: 'doconut'.
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 du middleware 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). C’est la couche de sécurité qui fonctionne comme prévu — voir Concepts de base → Sessions & Sécurité. Le refus est une image servie avec le statut 200, ainsi un moniteur qui ne vérifie que les codes d’état la compte comme une page.
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 (échec rapide) 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 prise en charge que par un plugin (ici : DICOM). Le plugin est enregistré, mais aucune licence ne lui accorde cette capacité désormais — généralement une licence Temporaire qui a expiré après le démarrage de l’application. Installez une licence qui la concède et vérifiez IsCapabilityGranted(LicenseCapability.Dicom) sur IDoconutLicenseService. Un droit non‑temporaire manquant ou insuffisant échoue normalement plus tôt, pendant AddDoconut().
FormatNotSupportedException :
Document format '<extension>' is not supported.Aucun visualiseur — intégré, plugin ou personnalisé — ne revendique 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 (p. 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.
Échecs au démarrage
InvalidOperationException mentionnant un plugin enregistré via AddPlugin — la licence actuelle non temporaire n'accorde pas cette capacité de plugin. Supprimez l'enregistrement ou installez une licence qui l'accorde. Une licence manquante et un fichier TRIAL hérité 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 en mode échec rapide — corrigez le chemin fautif.
Erreurs de compilation / dépendances
Erreur du compilateur CS1705, ou à l'exécution lors de l'ouverture d'un document :
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'Votre projet a épinglé System.Text.Json ou System.Text.Encodings.Web en dessous de la version 8.0.x des dépendances déclarées par Doconut.NET8. Supprimez la rétrogradation et laissez NuGet restaurer le graphique des paquets (System.Text.Json 8.0.5 et System.Text.Encodings.Web 8.0.0).
Le rendu semble incorrect
Les pages portent un filigrane — l'application est en mode d'évaluation : aucun fichier de licence trouvé, une licence Temporaire expirée, ou un domaine invalide. Sous une licence Temporaire active, seul le rendu du plugin est filigrané. Une construction publiée après la date d'abonnement d'une licence payante n'est pas filigranée : l'ouverture génère LicenseException. Examinez IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la référence IDoconutLicenseService de la page Licensing montre un point de terminaison prêt à l'emploi.
Les documents hérités 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 — le serveur ne possède pas les polices du document. Installez-les, ou pointez FontFolders (sur WordConfig/PptConfig) vers un dossier qui les contient. Sous Linux, voir ci-dessous.
Une annotation d'image apparaît dans le visualiseur mais l'exportation montre une boîte « Image bloquée » — l'hôte de l'image possède une adresse privée ou de boucle, que le serveur refuse de récupérer. Voir Annotations.
Linux
L'ouverture de tout document échoue avec :
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.Installez la bibliothèque de configuration des polices : apt-get install -y libfontconfig1 (fontconfig sur RHEL/Fedora). Voir Installation.
L'ouverture de tout document échoue avec :
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.L'application référence un SkiaSharp plus récent, directement ou via une autre bibliothèque. Ajoutez SkiaSharp.NativeAssets.Linux à la même version que ce SkiaSharp.
L'ouverture de tout document échoue avec :
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.L'hôte n'est pas une plateforme prise en charge. Alpine et autres distributions basées sur musl ne sont pas supportées : utilisez une image basée sur Debian ou Ubuntu.
Le texte est plus large ou plus étroit que sous Windows, ou les sauts de ligne diffèrent — les polices du document ne sont pas installées, donc Doconut utilise la police installée la plus proche. Installez des polices compatibles métriquement (fonts-liberation pour Arial, Times New Roman et Courier New ; fonts-crosextra-carlito et fonts-crosextra-caladea pour Calibri et Cambria), ou copiez vos propres polices sous licence vers /usr/share/fonts/ et exécutez fc-cache -f. Le texte asiatique affiché sous forme de cases vides nécessite fonts-noto-cjk.
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 enregistrés ou DICOM 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,
AllowSearchn'était pas activé au moment de l'ouverture. Word, Excel et PowerPoint exposent le même commutateur via leursPdfConfigimbriqués. - Le contenu est scanné/uniquement image, donc la Recherche normale n'a aucune couche de texte à 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 = falseafin qu'ils soient rendus via une projection PDF avec une couche de texte native. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB et MHT sont recherchables avec leurs paramètres de catalogue par défaut. objViewer.CanSearch()estfalseaprè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.- La page lit la valeur de retour de
objViewer.Search(...)— le compte arrive dans son troisième argument, un rappel.
Toujours bloqué ?
Isolez le problème avec l'application Quick Start minimale ; s'il se reproduit là, contactez le support avec le document, votre Program.cs, et la sortie des diagnostics de licence.
Cette page était-elle utile ?