Solución de problemas

Cada mensaje a continuación es el texto literal que produce Doconut, organizado por síntoma. Encuentra tu error y aplica la solución.

El visor no muestra nada

Área del visor vacía, consola del navegador llena de 404s para /doconut-res/...
UseDoconutResources() falta, o está colocado después de UseDoconut(). Debe ser el primero en la canalización.

HTTP 500 con:

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

La seguridad de token de Doconut (activada por defecto) necesita el estado de sesión de ASP.NET. Añade builder.Services.AddSession() y app.UseSession() antes de la rama de middleware de Doconut. El estado de sesión también necesita una caché: en una aplicación minimal-API añade builder.Services.AddDistributedMemoryCache(), o la aplicación se detiene al iniciar con Unable to resolve service for type 'IDistributedCache' (las aplicaciones MVC y Razor Pages ya registran una).

Una imagen de error en el área de la página que muestra:

You Are Not Authorized To View This Page.

El token fue abierto por una sesión de navegador diferente. Causas típicas: la cookie de sesión no llega a las solicitudes de la página (configuración de origen cruzado, política SameSite, un cliente API sin contenedor de cookies), o la aplicación se reinició (nuevas claves de sesión). Esta es la capa de seguridad funcionando como se diseñó — consulta Conceptos básicos → Sesiones y Seguridad.

Una imagen de error que muestra:

Document session not found. Please re-open document.

El token expiró (ventana deslizante, 60 minutos por defecto — DocOptions.TimeOut) o la sesión se cerró. Vuelve a abrir el documento para obtener un token nuevo.

Fallar al abrir un documento

LicenseException con un mensaje de rechazo — el archivo de licencia se encontró pero fue rechazado (firma inválida, manipulado, en lista negra, o una compilación fuera de la ventana de versión/actualización de la licencia). Este estado bloquea la apertura (fallo rápido) en lugar de degradar a una marca de agua; lee License.RejectionMessage para conocer la razón.

LicenseException:

This document type requires the 'Dicom' plugin license.

La extensión solo la maneja un plugin (aquí: DICOM) y la capacidad ya no está concedida. Registra el plugin y verifica lic.IsCapabilityGranted(LicenseCapability.Dicom). Un derecho no temporal faltante o insuficiente normalmente falla antes durante AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Ningún visor — incorporado, plugin o personalizado — reconoce esa extensión. Revisa la lista de formatos compatibles; para tus propios formatos, DoconutOptions.RegisterViewer puede agregar uno.

InvalidDataException — el contenido del archivo está corrupto o no coincide con su extensión (p. ej., un archivo renombrado). Valida las cargas antes de abrir.

InvalidOperationException:

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

Resolvió DocumentConverter sin registrar el plugin del Convertidor.

Fallo al iniciar

InvalidOperationException que menciona un plugin registrado mediante AddPlugin — la licencia no temporal actual no concede esa capacidad de plugin. Elimina el registro o instala una licencia que la conceda. Una licencia faltante y un archivo TRIAL heredado no conceden capacidades 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.

Validación de opciones de fallo rápido — corrige la ruta problemática.

Errores de compilación / dependencias

Error del compilador CS1705, o en tiempo de ejecución al abrir un documento:

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

Tu proyecto fijó System.Text.Json o System.Text.Encodings.Web por debajo de las dependencias 8.0.x declaradas por Doconut.NET6. Elimina la degradación y permite que NuGet restaure el grafo de paquetes (System.Text.Json 8.0.6 y System.Text.Encodings.Web 8.0.0 en el paquete auditado 26.7.0).

TypeInitializationException en el primer archivo de presentación:

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

El motor de presentación requiere estrictamente System.Drawing.Common 6.0.0 (declarado por el paquete). No elimines ni sobrescribas esa dependencia — cada apertura de PPT/PPTX/PPS/POT/ODP falla sin ella.

La salida se ve incorrecta

Las páginas llevan una marca de agua — la aplicación está en estado de evaluación: no se encontró archivo de licencia, una ventana temporal o de suscripción expirada, o un dominio inválido. Inspecciona IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la referencia IDoconutLicenseService de la página de Licenciamiento muestra un endpoint listo.

Los documentos heredados se renderizan con texto distorsionado — las codificaciones de página de códigos no se cargan por defecto en .NET 6. Añade una vez al iniciar:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Fuentes incorrectas o sustituidas en Linux/Docker — el contenedor carece de las fuentes del documento. Apunta FontFolders (en WordConfig/PptConfig) a un directorio de fuentes montado.

Las presentaciones se abren pero no se renderizan en Linux/macOS — el renderizador actual de PPT/PPTX/PPS/POT/ODP requiere libgdiplus nativo más System.Drawing.EnableUnixSupport=true. El paquete suministra System.Drawing.Common 6.0.0 porque es la última versión que respeta este interruptor.

La función funcionaba en evaluación, silenciosa en producción

La clásica sorpresa al pasar a producción: una licencia Temporal activa otorga todas las capacidades; tu licencia comprada solo otorga lo que adquiriste. Los paquetes de búsqueda y anotación pueden desaparecer cuando sus capacidades están ausentes. Los plugins de Convertidor o DICOM registrados con una licencia no temporal insuficiente fallan durante AddDoconut(). Compara IsCapabilityGranted(...) con cada función que habilites antes del despliegue.

La búsqueda no encuentra nada (o muy poco)

• Para un PDF directo, AllowSearch no estaba habilitado al abrir. Word, Excel y PowerPoint exponen el mismo interruptor a través de su PdfConfig anidado.
• El contenido es escaneado/sólo imagen, por lo que la Búsqueda normal no tiene capa de texto para coincidir. Usa una fuente con texto o una proyección PDF que preserve el texto.
• HTML y MS Project (MPP) no son buscables por defecto — establece DefaultRender = false para que se rendericen mediante una proyección PDF con una capa de texto nativa. Word, Excel, PowerPoint, TXT, Visio, correo electrónico, EPUB y MHT buscan en sus valores predeterminados del catálogo.
• objViewer.CanSearch() es false después de la inicialización — el formato resuelto no tiene una ruta de búsqueda estándar. Este veredicto es independiente de la licencia de Búsqueda; verifica ambas.

¿Aún atascado?

Aísla el problema con la aplicación mínima de Inicio Rápido; si se reproduce allí, contacta al soporte con el documento, tu Program.cs y la salida de diagnóstico de la licencia.