Solución de problemas

Cada mensaje a continuación es el texto literal que produce Doconut, organizado por síntoma. Encuentra tu error, 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 aparecer 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ñó — ver 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ó. 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 es manejada por un complemento (aquí: DICOM) y la capacidad ya no está concedida. Registra el complemento y verifica 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 — reconoce esa extensión. Verifica la lista de formatos soportados; 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>().

Has resuelto DocumentConverter sin registrar el complemento Converter.

Fallo al iniciar

InvalidOperationException que menciona un complemento registrado mediante AddPlugin — la licencia no temporal actual no concede esa capacidad de complemento. Elimina el registro o instala 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 — 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 al IDoconutLicenseService de la página de Licenciamiento 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 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 funcionó en evaluación, pero está silenciosa en producción

La sorpresa clásica al lanzar: 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 complementos Converter o DICOM registrados con una licencia no temporal insuficiente fallan durante AddDoconut(). Compara IsCapabilityGranted(...) con cada característica 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 separado de la licencia de Búsqueda; verifica ambos.

¿Aún atascado?

Aísla el problema contra 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.