Solução de Problemas

Todas as mensagens abaixo são o texto literal que o Doconut produz, organizadas por sintoma. Encontre seu erro e 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 execução.

HTTP 500 com:

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

A segurança de token do Doconut (ativada por padrão) requer 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 falhará 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 requisições da página (configuração cross-origin, política SameSite, um cliente API sem 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 e 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.

O servidor está ok, mas a página se comporta incorretamente — sem erro algum

Estes são os modos de falha que devem ser suspeitos primeiro ao avançar uma aplicação. Todos os três deixam o servidor funcionando perfeitamente, renderizam o documento corretamente e não reportam nada no console do navegador.

Um spinner de carregamento que nunca para.
Seus callbacks do visualizador são declarados como funções globais nomeadas após o id do contêiner — ctlDoc_OnViewerReady() e afins. O visualizador anterior procurava esses nomes; este não. O manipulador que ocultaria o spinner simplesmente nunca é executado. Passe as funções como opções em vez disso:

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

A lista completa de opções está em ConfiguraçõesDoVisualizador.

Ícones ou chrome do visualizador ausentes, páginas corretas de outra forma.
ResPath está vazio ou aponta para a raiz da aplicação — correto na biblioteca anterior, errado aqui. Ele deve nomear o prefixo que UseDoconutResources() monta:

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

Ladrilhos quebrados nas páginas posteriores ao servir de armazenamento compartilhado.
Páginas que ainda estão sendo gravadas respondem 202 Accepted. Um cliente sem retryOn409: true trata isso como uma imagem falha. Veja Implantações Distribuídas.

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) 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 — embutido, plugin ou personalizado — 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 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 de opções fail‑fast — corrija o caminho problemático.

Erros de compilação / dependência

O pacote não será instalado de forma alguma — Doconut.NETStandard 26.8.0 tem como alvo netstandard2.1, portanto o NuGet recusa um projeto .NET Framework. Este não é um erro de restauração resolvível: .NET Framework não pode consumir netstandard2.1. Use o pacote Doconut.NETFramework em vez disso.

Erro de compilador CS1705, ou em tempo de execução ao abrir um documento:

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

Seu projeto fixou System.Text.Json ou System.Text.Encodings.Web abaixo das dependências 9.0.x declaradas por Doconut.NETStandard. Remova o downgrade e deixe o NuGet restaurar o grafo de pacotes (System.Text.Json 9.0.0 e System.Text.Encodings.Web 9.0.0 no pacote auditado 26.8.0).

Uma parede de erros de compilação imediatamente após atualizar o pacote — isso é esperado. 26.8.0 tem uma superfície de API diferente da 26.7.0, não é uma atualização compatível. A maioria dos erros são as linhas using que foram movidas para o namespace raiz Doconut; siga o guia Migrar para .NET Standard 2.1 em vez de corrigir uma a uma.

TypeInitializationException no primeiro arquivo de apresentação:

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

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

A saída parece errada

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

Documentos legados renderizam texto corrompido — codificações de página de código não são carregadas por padrão. 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 respeita essa configuração.

Recurso funcionava em avaliação, mas está silencioso em produção

A surpresa clássica 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 de Conversor ou DICOM registrados 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, 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 é 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 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 são pesquisáveis em seus padrões de catálogo.
• objViewer.CanSearch() retorna false após a inicialização — o formato resolvido não possui caminho de busca padrão. Esse veredicto é separado da licença de Busca; verifique ambos.

Ainda está 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.