Solução de Problemas

Todas as mensagens abaixo são o texto literal que o Doconut produz, organizadas por sintoma. Encontre seu erro, aplique a correção.

O visualizador não exibe nada

Área do visualizador vazia, console do navegador cheio de 404s para /doconut-res/...
UseDoconutResources() está ausente, ou foi colocado após UseDoconut(). Ele deve ser o primeiro na cadeia de processamento.

HTTP 500 com:

Session middleware not configured. Call UseSession() before UseDoconut().

A segurança de token do Doconut (ativada por padrão) precisa do estado de sessão do ASP.NET. Adicione builder.Services.AddSession() e app.UseSession() antes do ramo de middleware do Doconut.

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 requisições da página (configuração cross‑origin, política SameSite, cliente API sem jar de cookies), ou a aplicação foi reiniciada (novas chaves de sessão). Essa é a camada de segurança funcionando como projetado — veja Conceitos Principais → Sessões & Segurança.

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 (fail‑fast) 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) e a capacidade não está mais concedida. Registre o plugin e verifique lic.IsCapabilityGranted(LicenseCapability.Dicom). Uma concessão ausente ou insuficiente não‑temporária normalmente falha antes durante AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Nenhum visualizador — interno, plugin ou customizado — reconhece 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 Converter.

Falha na inicialização

InvalidOperationException mencionando um plugin registrado via AddPlugin — a licença não‑temporária atual 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 de opções fail‑fast — 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=10.0.0.0'

Seu projeto fixou System.Text.Json / System.Text.Encodings.Web abaixo de 10.0.x. Remova o downgrade e deixe o NuGet restaurar as versões declaradas por Doconut.NET8.

TypeInitializationException no primeiro arquivo de apresentação:

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

O motor de apresentação requer rigidamente System.Drawing.Common 6.0.0 (declarado pelo pacote). Não remova ou sobrescreva essa dependência — toda abertura de PPT/PPTX/PPS/POT/ODP falha sem ela.

A saída parece errada

Páginas carregam uma marca d'água — a aplicação está em estado de avaliação: nenhum arquivo de licença encontrado, janela temporária ou de assinatura expirada, ou domínio inválido. Inspecione IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — a referência da página de Licenciamento ao IDoconutLicenseService mostra um endpoint pronto.

Documentos legados renderizam texto corrompido — 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 no Linux/Docker — o contêiner não possui as fontes do documento. Aponte FontFolders (em WordConfig/PptConfig) para um diretório de fontes montado.

Apresentações abrem mas falham ao renderizar no Linux/macOS — o renderizador atual de PPT/PPTX/PPS/POT/ODP requer libgdiplus nativo mais System.Drawing.EnableUnixSupport=true. O pacote fornece System.Drawing.Common 6.0.0 porque essa é a última versão que honra essa alternância.

Recurso funcionava em avaliação, silencioso em produção

A clássica surpresa ao entrar em produção: uma licença Temporária ativa concede todas as capacidades; sua licença comprada concede apenas o que foi adquirido. Pacotes de busca e anotação podem desaparecer quando suas capacidades estão ausentes. Plugins Converter ou DICOM registrados com 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, AllowSearch não foi habilitado no momento da abertura. Word, Excel e PowerPoint expõem a mesma opção através do seu PdfConfig aninhado.
• O conteúdo está escaneado/apenas imagem, então a Busca normal não tem camada de texto para corresponder. Use uma fonte que contenha texto ou uma projeção PDF que preserve o texto.
• HTML e MS Project (MPP) não são pesquisáveis por padrão — defina DefaultRender = false para que eles sejam renderizados via projeção PDF com camada de texto nativa. Word, Excel, PowerPoint, TXT, Visio, email, EPUB e MHT pesquisam em seus padrões de catálogo.
• objViewer.CanSearch() é false após a inicialização — o formato resolvido não tem caminho de busca padrão. Esse veredicto é separado da licença de Busca; verifique ambos.

Ainda preso?

Isole o problema contra o aplicativo Quick Start mínimo; se ele se reproduzir lá, entre em contato com o suporte enviando o documento, seu Program.cs e a saída de diagnóstico da licença.