Solución de problemas
Diagnosticar errores comunes
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.
El visor informa The viewer handler could not be reached (no response).
La solicitud nunca recibió una respuesta. Una causa común es un BasePath que comienza con /: '/doconut' se convierte en //doconut/DocImage.axd, una solicitud a otro host. Escríbelo sin la barra inicial (BasePath: 'doconut').
El visor informa Please make sure your middleware is configured.
El punto final de la página respondió 404: UseDoconut() no está montado donde apunta el BasePath del cliente. Con app.Map("/doconut", branch => branch.UseDoconut()), el cliente usa BasePath: 'doconut'.
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 del middleware 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 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 cross-origin, 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. La denegación es una imagen servida con el estado 200, por lo que un monitor que solo verifica códigos de estado la cuenta como una página.
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 es manejada solo por un plugin (aquí: DICOM). El plugin está registrado, pero ninguna licencia otorga su capacidad ahora — típicamente una licencia Temporal que expiró después de que la aplicación se inició. Instala una licencia que la conceda y verifica IsCapabilityGranted(LicenseCapability.Dicom) en IDoconutLicenseService. Una autorización 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 soportados; 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>().Resolviste DocumentConverter sin registrar el plugin Converter.
Fallos al iniciar
InvalidOperationException mentioning a plugin registered via AddPlugin — la licencia actual no temporal no otorga esa capacidad de plugin. Elimine el registro o instale una licencia que lo conceda. Una licencia faltante y un archivo legacy TRIAL no conceden capacidades de plugin.
ArgumentException from 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 falla rápida — corrija la ruta problemática.
Errores de compilación / dependencias
Error de compilación 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'Su proyecto fijó System.Text.Json o System.Text.Encodings.Web por debajo de las dependencias 8.0.x declaradas por Doconut.NET8. Elimine la degradación y permita que NuGet restaure el grafo de paquetes (System.Text.Json 8.0.5 y System.Text.Encodings.Web 8.0.0).
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 licencia Temporal expirada o un dominio inválido. Con una licencia Temporal activa, solo la salida del plugin lleva marca de agua. Una compilación publicada después de la fecha de suscripción de una licencia paga no lleva marca de agua: al abrir lanza LicenseException. Inspeccione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — la referencia IDoconutLicenseService de la página de Licencias muestra un endpoint listo.
Los documentos heredados muestran texto corrupto — las codificaciones de página de códigos no se cargan por defecto en .NET 8. Añada una vez al iniciar:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Fuentes incorrectas o sustituidas — el servidor carece de las fuentes del documento. Instálelas, o apunte FontFolders (en WordConfig/PptConfig) a una carpeta que las contenga. En Linux, vea más abajo.
Una anotación de imagen se muestra en el visor pero la exportación tiene un cuadro "Imagen bloqueada" — el host de la imagen tiene una dirección privada o de bucle invertido, que el servidor se niega a obtener. Vea Anotaciones.
Linux
Abrir cualquier documento falla con:
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.Instale la biblioteca de configuración de fuentes: apt-get install -y libfontconfig1 (fontconfig en RHEL/Fedora). Vea Instalación.
Abrir cualquier documento falla con:
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.La aplicación hace referencia a una versión más reciente de SkiaSharp, directa o indirectamente a través de otra biblioteca. Añada SkiaSharp.NativeAssets.Linux con la misma versión que ese SkiaSharp.
Abrir cualquier documento falla con:
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.El host no es una plataforma compatible. Alpine y otras distribuciones basadas en musl no son compatibles: use una imagen basada en Debian o Ubuntu.
El texto es más ancho o más estrecho que en Windows, o las líneas se ajustan de forma diferente — las fuentes del documento no están instaladas, por lo que Doconut usa la fuente instalada más cercana. Instale fuentes compatibles métricamente (fonts-liberation para Arial, Times New Roman y Courier New; fonts-crosextra-carlito y fonts-crosextra-caladea para Calibri y Cambria), o copie sus propias fuentes con licencia a /usr/share/fonts/ y ejecute fc-cache -f. El texto asiático que se muestra como cuadros vacíos necesita fonts-noto-cjk.
Funcionalidad funciona en evaluación, silenciosa en producción
La clásica sorpresa 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 Registered Converter o DICOM 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,
AllowSearchno estaba habilitado al abrirlo. Word, Excel y PowerPoint exponen el mismo interruptor a través de suPdfConfiganidado. - El contenido es escaneado/sólo 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 en sus valores predeterminados — configure
DefaultRender = falsepara 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()esfalsedespué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.- La página lee el valor de retorno de
objViewer.Search(...)— el recuento llega en su tercer argumento, una devolución de llamada.
¿Aún atascado?
Aísle el problema con la aplicación Quick Start mínima; si se reproduce allí, contacte al soporte con el documento, su Program.cs y la salida de diagnóstico de la licencia.
¿Fue útil esta página?