トラブルシューティング

一般的なエラーを診断する

以下のメッセージはすべて 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=8.0.0.0'

プロジェクトが Doconut.NET6 が宣言する 8.0.x 依存関係よりも低いバージョンの System.Text.Json または System.Text.Encodings.Web に固定しています。ダウングレードを解除し、NuGet にパッケージグラフを復元させてください（監査済み 26.7.0 パッケージでは System.Text.Json 8.0.6 と System.Text.Encodings.Web 8.0.0 が使用されています）。

最初のプレゼンテーションファイルでの 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 6 ではコードページエンコーディングがデフォルトでロードされません。起動時に一度だけ追加してください:

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

それでも解決しない場合

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

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