Solução de Problemas
Diagnosticar erros comuns
Cada mensagem abaixo é o texto literal que o Doconut produz, organizado por sintoma. Encontre seu erro, aplique a correção.
O visualizador não mostra nada
Área do visualizador vazia, console do navegador cheio de 404s para /doconut-res/...
UseDoconutResources() está ausente, ou colocado após UseDoconut(). Ele deve ser o primeiro na cadeia de processamento.
O visualizador relata The viewer handler could not be reached (no response).
A solicitação nunca recebeu uma resposta. Uma causa comum é um BasePath que começa com /: '/doconut' torna-se //doconut/DocImage.axd, uma solicitação para outro host. Escreva sem a barra inicial (BasePath: 'doconut').
O visualizador relata Please make sure your middleware is configured.
O ponto de extremidade da página respondeu 404: UseDoconut() não está montado onde o BasePath do cliente aponta. Com app.Map("/doconut", branch => branch.UseDoconut()), o cliente usa BasePath: 'doconut'.
HTTP 500 com:
Session middleware not configured. Call UseSession() before UseDoconut().A segurança de token do Doconut (ativada por padrão) requer o estado de sessão do ASP.NET. Adicione builder.Services.AddSession() e app.UseSession() antes do ramo de middleware do Doconut. O estado de sessão também precisa de um cache: em um aplicativo minimal-API adicione builder.Services.AddDistributedMemoryCache(), ou o aplicativo para na inicialização com Unable to resolve service for type 'IDistributedCache' (aplicativos MVC e Razor Pages já registram um).
Uma imagem de erro na área da página exibindo:
You Are Not Authorized To View This Page.O token foi aberto por uma sessão de navegador diferente. Causas típicas: o cookie de sessão não está chegando às solicitações da página (configuração cross-origin, política SameSite, um cliente API sem um jar de cookies), ou o aplicativo reiniciou (novas chaves de sessão). Esta é a camada de segurança funcionando como projetado — veja Conceitos Principais → Sessões & Segurança. A recusa é uma imagem servida com status 200, portanto um monitor que verifica apenas códigos de status a conta como uma página.
Uma imagem de erro exibindo:
Document session not found. Please re-open document.O token expirou (janela deslizante, padrão 60 minutos — DocOptions.TimeOut) ou a sessão foi encerrada. Reabra o documento para obter um token novo.
Falha ao abrir um documento
LicenseException com uma mensagem de rejeição — o arquivo de licença foi encontrado, mas rejeitado (assinatura inválida, adulterado, na lista negra, ou uma compilação fora da janela de versão/atualização da licença). Esse estado bloqueia a abertura (falha rápida) em vez de degradar para uma marca d'água; leia License.RejectionMessage para saber o motivo.
LicenseException:
This document type requires the 'Dicom' plugin license.A extensão é tratada apenas por um plugin (aqui: DICOM). O plugin está registrado, mas nenhuma licença concede sua capacidade mais — tipicamente uma licença Temporária que expirou após o início do aplicativo. Instale uma licença que a conceda e verifique IsCapabilityGranted(LicenseCapability.Dicom) em IDoconutLicenseService. Uma concessão não temporária ausente ou insuficiente normalmente falha antes, durante AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Nenhum visualizador — interno, plugin ou personalizado — aceita essa extensão. Verifique a lista de formatos suportados; para seus próprios formatos, DoconutOptions.RegisterViewer pode adicionar um.
InvalidDataException — o conteúdo do arquivo está corrompido ou não corresponde à sua extensão (ex.: um arquivo renomeado). Valide os uploads antes de abrir.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Você resolveu DocumentConverter sem registrar o plugin Conversor.
Falhas na inicialização
InvalidOperationException mencionando um plugin registrado via AddPlugin — a licença atual não temporária não concede essa capacidade de plugin. Remova o registro ou instale uma licença que a conceda. Uma licença ausente e um arquivo legado TRIAL não concedem 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.Validação das opções de falha rápida — corrija o caminho problemático.
Erros de compilação / dependência
Erro de compilador CS1705, ou em tempo de execução ao abrir um documento:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'Seu projeto fixou System.Text.Json ou System.Text.Encodings.Web abaixo das dependências 8.0.x declaradas por Doconut.NET8. Remova a redução de versão e deixe o NuGet restaurar o grafo de pacotes (System.Text.Json 8.0.5 e System.Text.Encodings.Web 8.0.0).
A saída parece errada
Páginas carregam uma marca d'água — o aplicativo está em estado de avaliação: nenhum arquivo de licença encontrado, uma licença Temporária expirada ou um domínio inválido. Sob uma licença Temporária ativa, apenas a saída do plugin recebe marca d'água. Uma compilação lançada após a data de assinatura de uma licença paga não recebe marca d'água: ao abrir lança LicenseException. Inspecione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — a referência IDoconutLicenseService da página de Licenciamento mostra um endpoint pronto.
Documentos legados renderizam texto corrompido — as codificações de página de código não são carregadas por padrão no .NET 8. Adicione uma única vez na inicialização:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Fontes erradas ou substituídas — o servidor não possui as fontes do documento. Instale-as, ou aponte FontFolders (em WordConfig/PptConfig) para uma pasta que as contenha. No Linux, veja abaixo.
Uma anotação de imagem aparece no visualizador, mas a exportação tem uma caixa "Imagem bloqueada" — o host da imagem tem um endereço privado ou de loopback, que o servidor se recusa a buscar. Veja Anotações.
Linux
Abrir qualquer documento falha com:
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 a biblioteca de configuração de fontes: apt-get install -y libfontconfig1 (fontconfig no RHEL/Fedora). Veja Instalação.
Abrir qualquer documento falha com:
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.O aplicativo referencia um SkiaSharp mais recente, direta ou indiretamente através de outra biblioteca. Adicione SkiaSharp.NativeAssets.Linux na mesma versão desse SkiaSharp.
Abrir qualquer documento falha com:
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.O host não é uma plataforma suportada. Alpine e outras distribuições baseadas em musl não são suportadas: use uma imagem baseada em Debian ou Ubuntu.
O texto é mais largo ou mais estreito que no Windows, ou as quebras de linha são diferentes — as fontes do documento não estão instaladas, então Doconut usa a fonte instalada mais próxima. Instale fontes compatíveis metricamente (fonts-liberation para Arial, Times New Roman e Courier New; fonts-crosextra-carlito e fonts-crosextra-caladea para Calibri e Cambria), ou copie suas próprias fontes licenciadas para /usr/share/fonts/ e execute fc-cache -f. Texto asiático exibido como caixas vazias requer fonts-noto-cjk.
Recurso funcionava na avaliação, silencioso na produção
A clássica surpresa ao entrar em produção: uma licença Temporária ativa concede todas as funcionalidades; sua licença comprada concede apenas o que você adquiriu. Pacotes de busca e anotação podem desaparecer quando suas funcionalidades estão ausentes. Conversor Registrado ou plugins DICOM com uma licença não‑temporária insuficiente falham durante AddDoconut(). Compare IsCapabilityGranted(...) com cada recurso que você habilita antes da implantação.
Busca não encontra nada (ou muito pouco)
- Para um PDF direto,
AllowSearchnão foi ativado no momento da abertura. Word, Excel e PowerPoint expõem a mesma opção através de seusPdfConfiganinhados. - O conteúdo é escaneado/apenas imagem, portanto a Busca normal não tem camada de texto para corresponder. Use uma fonte que contenha texto ou uma projeção de PDF que preserve o texto.
- HTML e MS Project (MPP) não são pesquisáveis em suas configurações padrão — configure
DefaultRender = falsepara que sejam renderizados via projeção de PDF com camada de texto nativa. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB e MHT são pesquisáveis em suas configurações padrão de catálogo. objViewer.CanSearch()estáfalseapós a inicialização — o formato resolvido não possui caminho de busca padrão. Este veredicto é separado da licença de Busca; verifique ambos.- A página lê o valor de retorno de
objViewer.Search(...)— a contagem chega em seu terceiro argumento, um callback.
Ainda preso?
Isole o problema usando o aplicativo Quick Start mínimo; se ele se reproduzir lá, entre em contato com o suporte com o documento, seu Program.cs e a saída de diagnóstico da licença.
Esta página foi útil?