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 404 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 tokens 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 detendrá 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 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ó. Vuelve a abrir el documento para obtener un token nuevo.

El servidor está bien pero la página se comporta mal — sin error en ningún lado

Estos son los modos de falla que se deben sospechar primero al avanzar una aplicación. Los tres dejan el servidor funcionando perfectamente, renderizan el documento correctamente y no reportan nada en la consola del navegador.

Un indicador de carga que nunca se detiene. Tus callbacks del visor están declarados como funciones globales nombradas según el id del contenedor — ctlDoc_OnViewerReady() y sus amigas. El visor anterior buscaba esos nombres; este no. El manejador que habría ocultado el indicador simplemente nunca se ejecuta. Pasa las funciones como opciones en su lugar:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

El documento detrás del indicador está bien. La lista completa de opciones está en ConfiguraciónDelVisor.

Faltan íconos del visor o la barra, pero las páginas están correctas. ResPath está vacío o apunta a la raíz de la aplicación — correcto en la biblioteca anterior, incorrecto aquí. Debe nombrar el prefijo que monta UseDoconutResources():

ResPath: 'doconut-res/images'   // o '<your ResourcesPath>/images'

Mosaicos rotos en páginas posteriores al servir desde almacenamiento compartido. Las páginas que aún se están escribiendo responden 202 Accepted. Un cliente sin retryOn409: true trata eso como una imagen fallida. Vea DesplieguesDistribuidos.

Fallos 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 (fail‑fast) 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). Una autorización faltante o insuficiente que no sea temporal 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 admitidos; para tus propios formatos, DoconutOptions.RegisterViewer puede añadir 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 plugin del convertidor.

Fallos al iniciar

InvalidOperationException que menciona un plugin registrado mediante AddPlugin — la licencia actual que no es temporal no otorga esa capacidad de plugin. Elimine el registro o instale una licencia que lo conceda. Una licencia faltante y un archivo TRIAL heredado no otorgan 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 que falla rápidamente — corrija la ruta ofensiva.

Errores de compilación / dependencias

El paquete no se instalará en absoluto — Doconut.NETStandard 26.8.0 apunta a
netstandard2.1, por lo que NuGet rechaza un proyecto .NET Framework. Este no es un error de restauración resoluble: .NET Framework no puede consumir netstandard2.1. Use el paquete
Doconut.NETFramework en su lugar.

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

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

Su proyecto fijó System.Text.Json o System.Text.Encodings.Web por debajo de la versión 9.0.x
de las dependencias declaradas por Doconut.NETStandard. Elimine la degradación y permita que NuGet restaure el
grafo de paquetes (System.Text.Json 9.0.0 y System.Text.Encodings.Web 9.0.0 en el
paquete auditado 26.8.0).

Una pared de errores de compilación inmediatamente después de actualizar el paquete — esto es esperado.
26.8.0 tiene una superficie de API diferente a la 26.7.0, no es una actualización compatible. La mayoría de los
errores son las líneas using que se movieron al espacio de nombres raíz Doconut; siga la guía
Migrar a .NET Standard 2.1 en lugar de parchearlos uno por uno.

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 — 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 caducada, o un dominio no válido. Inspeccione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la referencia IDoconutLicenseService de la página de Licencias muestra un punto final listo para usar.

Los documentos heredados renderizan texto distorsionado — las codificaciones de página de códigos no se cargan por defecto. Añada 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 esa 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 plugins 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 abrirlo. 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 que contenga 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.

¿Sigues atascado?

Aísla el problema en la aplicación mínima de Quick Start; si se reproduce allí, contacta con el soporte con el documento, tu Program.cs, y la salida de diagnóstico de la licencia.