トラブルシューティング

一般的なエラーを診断

以下のメッセージはすべて 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 ミドルウェアブランチの 前 に追加してください。

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

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（AddPlugin で登録されたプラグインに言及） — 現在の非一時的ライセンスはそのプラグイン機能を付与していません。登録を削除するか、機能を付与するライセンスをインストールしてください。ライセンスが欠如している、またはレガシーな TRIAL ファイルではプラグイン機能は付与されません。

ArgumentException（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.

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

ビルド / 依存関係エラー

コンパイラエラー CS1705、またはドキュメントオープン時のランタイムエラー

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

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 でフォントが間違っている、または置き換えられている — コンテナにドキュメントのフォントがありません。FontFolders（WordConfig/PptConfig 上）をマウントしたフォントディレクトリに設定してください。

プレゼンテーションは開くが 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 です — 解決されたフォーマットに標準的な検索パスがありません。この判定は検索ライセンスとは別であり、両方を確認してください。

まだ解決しない場合は？

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

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