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().

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

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 almacén de cookies), o la aplicación se reinició (nuevas claves de sesión). Esta es la capa de seguridad funcionando como se diseñó — vea Conceptos básicos → Sesiones y Seguridad.

Una imagen de error que dice:

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ó. Vuelva 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; lea License.RejectionMessage para conocer la razón.

LicenseException:

This document type requires the 'Dicom' plugin license.

La extensión solo es manejada por un complemento (aquí: DICOM) y la capacidad ya no está concedida. Registre el complemento y verifique lic.IsCapabilityGranted(LicenseCapability.Dicom). Una autorización no temporal faltante o insuficiente normalmente falla antes durante AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Ningún visor — incorporado, complemento o personalizado — admite esa extensión. Verifique la lista de formatos compatibles; para sus 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). Valide 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 complemento Converter.

Fallo al iniciar

InvalidOperationException que menciona un complemento registrado vía AddPlugin — la licencia no temporal actual no concede esa capacidad de complemento. Elimine el registro o instale una licencia que la conceda. Una licencia faltante y un archivo TRIAL heredado no otorgan capacidades de complementos.

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 — corrija 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=10.0.0.0'

Su proyecto fijó System.Text.Json / System.Text.Encodings.Web por debajo de 10.0.x. Elimine la degradación y permita que NuGet restaure las versiones que declara Doconut.NET8.

TypeInitializationException en el primer archivo de presentación:

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

El motor de presentaciones requiere estrictamente System.Drawing.Common 6.0.0 (declarado por el paquete). No elimine ni sobrescriba esa dependencia — toda 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. Inspeccione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la referencia al IDoconutLicenseService de la página de Licencias muestra un endpoint listo para usar.

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

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Fuentes incorrectas o sustituidas en Linux/Docker — el contenedor carece de las fuentes del documento. Apunte 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 funcionó en evaluación, pero está silenciosa en producción

La sorpresa clásica al pasar a producción: una licencia Temporal activa otorga todas las capacidades; su licencia comprada solo otorga lo que adquirió. Los paquetes de búsqueda y anotación pueden desaparecer cuando sus capacidades están ausentes. Los complementos Converter o DICOM registrados con una licencia no temporal insuficiente fallan durante AddDoconut(). Compare IsCapabilityGranted(...) con cada función que habilite 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 / solo imagen, por lo que la Búsqueda normal no tiene capa de texto para coincidir. Use una fuente con texto o una proyección PDF que preserve el texto.
• HTML y MS Project (MPP) no son buscables por defecto — establezca 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; verifique ambos.

¿Aún atascado?

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