トラブルシューティング

一般的なエラーの診断

以下のメッセージはすべて 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 ポリシー、クッキー jar を持たない 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 ファイルではプラグイン機能は付与されません。

AddDoconut() からの ArgumentException：

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'

プロジェクトで System.Text.Json または System.Text.Encodings.Web を Doconut.NET6 が宣言する 8.0.x より下のバージョンに固定しています。ダウングレードを削除し、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、ライセンス診断出力を添えてサポートに問い合わせてください。

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