トラブルシューティング

一般的なエラーの診断

以下のメッセージはすべて Doconut が出力する文字列で、症状別に整理されています。エラーを見つけて、修正を適用してください。

ビューアが何も表示しない

ビューア領域が空で、ブラウザコンソールに /doconut-res/... の 404 が多数表示される
UseDoconutResources() が欠如しているか、UseDoconut() の後に配置されています。パイプラインの最初に配置する必要があります。

HTTP 500 が発生

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

Doconut のトークンセキュリティ（デフォルトで有効）は ASP.NET のセッション状態を必要とします。builder.Services.AddSession() と app.UseSession() を Doconut ミドルウェアブランチの 前に 追加してください。セッション状態にはキャッシュも必要です。最小 API アプリの場合は builder.Services.AddDistributedMemoryCache() を追加するか、Unable to resolve service for type 'IDistributedCache' というエラーで起動時に停止します（MVC および Razor Pages アプリは既に登録されています）。

ページ領域に表示されるエラー画像のテキスト:

text
You Are Not Authorized To View This Page.

トークンは別のブラウザセッションで開かれました。典型的な原因は、セッションクッキーがページリクエストに届いていないこと（クロスオリジン設定、SameSite ポリシー、クッキージャーを持たない API クライアント）、またはアプリが再起動したこと（新しいセッションキー）です。これは設計通りに機能しているセキュリティ層です — Core Concepts → Sessions & Security を参照してください。

エラー画像のテキスト:

text
Document session not found. Please re-open document.

トークンが期限切れになった（スライディングウィンドウ、デフォルト 60 分 — DocOptions.TimeOut）か、セッションが閉じられました。新しいトークンを取得するためにドキュメントを再度開いてください。

ドキュメントのオープンに失敗する

LicenseException と拒否メッセージ — ライセンスファイルは見つかりましたが、拒否されました（署名が無効、改ざん、ブラックリスト登録、またはライセンスのバージョン/更新ウィンドウ外のビルド）。この状態では、透かしに降格するのではなくオープンがブロックされます（即座に失敗）。理由は License.RejectionMessage を参照してください。

LicenseException:

text
This document type requires the 'Dicom' plugin license.

拡張子はプラグイン（ここでは DICOM）のみが処理でき、機能が付与されていません。プラグインを登録し、lic.IsCapabilityGranted(LicenseCapability.Dicom) を確認してください。欠如または不十分な非一時的権利は通常 AddDoconut() の段階で早期に失敗します。

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

拡張子がサポートされていません（組み込み、プラグイン、カスタムのいずれのビューアもその拡張子を扱いません）。サポートされているフォーマット一覧を確認してください。独自フォーマットの場合は、DoconutOptions.RegisterViewer で追加できます。

InvalidDataException — ファイル内容が破損しているか、拡張子と一致しません（例：名前を変更したファイル）。オープン前にアップロードを検証してください。

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter を解決しましたが、Converter プラグインが登録されていません。

起動に失敗する

InvalidOperationException mentioning a plugin registered via AddPlugin — 現在の非一時的ライセンスはそのプラグイン機能を付与していません。登録を削除するか、機能を付与するライセンスをインストールしてください。ライセンスが欠如している場合やレガシーな TRIAL ファイルはプラグイン機能を付与しません。

ArgumentException from AddDoconut():

text
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.

即座に失敗するオプション検証です — 該当するパスを修正してください。

ビルド / 依存関係エラー

Compiler error CS1705, or at runtime when opening a document:

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

プロジェクトで System.Text.Json / System.Text.Encodings.Web を 10.0.x 未満に固定しています。ダウングレードを解除し、Doconut.NET8 が宣言するバージョンを NuGet に復元させてください。

TypeInitializationException on the first presentation file:

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

プレゼンテーションエンジンは System.Drawing.Common 6.0.0 をハード依存しています（パッケージで宣言）。この依存関係を削除したり上書きしたりしないでください — それが無いとすべての PPT/PPTX/PPS/POT/ODP のオープンが失敗します。

出力が正しくない

ページに透かしが表示される — アプリが評価モードです：ライセンスファイルが見つからない、期限切れの一時またはサブスクリプションウィンドウ、または無効なドメインです。IDoconutLicenseService（License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage）を確認してください — ライセンスページの IDoconutLicenseService 参照は既成のエンドポイントを示しています。

レガシードキュメントが文字化け — .NET 8 ではコードページエンコーディングがデフォルトでロードされません。起動時に一度だけ以下を追加してください:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker でフォントが間違っている、または置き換わっている — コンテナにドキュメントのフォントがありません。WordConfig/PptConfig の FontFolders をマウントしたフォントディレクトリに設定してください。

プレゼンテーションは開くが Linux/macOS でレンダリングに失敗 — 現在の PPT/PPTX/PPS/POT/ODP レンダラはネイティブ libgdiplus と System.Drawing.EnableUnixSupport=true を必要とします。パッケージは System.Drawing.Common 6.0.0 を提供しています。これはこのスイッチを最後にサポートしたバージョンです。

評価版では機能したが本番環境では無効

典型的な本番リリース時の驚き：アクティブな一時ライセンスはすべての機能を付与しますが、購入したライセンスは購入した機能だけを付与します。検索や注釈バンドルは、対応する機能が無いと消失することがあります。非一時的ライセンスが不十分な場合、登録された Converter や DICOM プラグインは AddDoconut() 時に失敗します。デプロイ前に有効にするすべての機能に対して IsCapabilityGranted(...) を比較してください。

検索で何も見つからない（または少なすぎる）

  • 直接 PDF の場合、オープン時に AllowSearch が有効になっていませんでした。Word、Excel、PowerPoint はそれぞれのネストされた PdfConfig で同じスイッチを公開しています。
  • コンテンツがスキャン画像のみの場合、通常の検索はマッチするテキスト層がありません。テキストを含むソースまたはテキストを保持した PDF 投影を使用してください。
  • HTML と MS Project (MPP) はデフォルトでは検索できません — DefaultRender = false に設定すると、PDF 投影を通じてネイティブテキスト層でレンダリングされます。Word、Excel、PowerPoint、TXT、Visio、メール、EPUB、MHT はカタログのデフォルト設定で検索可能です。
  • 初期化後に objViewer.CanSearch() が false です — 解決されたフォーマットに標準の検索パスがありません。この判定は Search ライセンスとは別なので、両方を確認してください。

まだ解決しないですか？

最小構成の Quick Start アプリで問題を切り分けてみてください。そこで再現する場合は、ドキュメント、Program.cs、ライセンス診断出力を添えてサポートにお問い合わせください。

このページは役に立ちましたか？