トラブルシューティング

一般的なエラーの診断

以下のメッセージはすべて 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）またはセッションが閉じられました。新しいトークンを取得するためにドキュメントを再度開いてください。

サーバーは正常だがページが異常動作する — エラーが全く出ない場合

以下は、アプリケーションを引き継いだ際に最初に疑うべき失敗モードです。3 つすべてともサーバーは正常に動作し、ドキュメントは正しくレンダリングされ、ブラウザコンソールには何も報告されません。

決して止まらないビジー スピナー。 ビューアのコールバックがコンテナ ID にちなんだグローバル関数（例: ctlDoc_OnViewerReady() など）として宣言されています。以前のビューアはそれらの名前を検索しましたが、今回のビューアは検索しません。スピナーを非表示にするハンドラが実行されないためです。代わりに関数をオプションとして渡してください:

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

スピナーの背後のドキュメントは問題ありません。全オプション一覧は ビューア設定 にあります。

ビューアのアイコンや Chrome が欠如、ページはそれ以外は正しい。 ResPath が空であるか、アプリケーションのルートを指しています — 前のライブラリでは正しかったが、こちらでは間違いです。UseDoconutResources() がマウントするプレフィックス名を指定する必要があります:

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

共有ストレージから配信する際の後続ページでタイルが壊れる。 まだ書き込み中のページは 202 Accepted を返します。retryOn409: true が設定されていないクライアントはそれを画像取得失敗とみなします。 分散デプロイ を参照してください。

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

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.

Fail-fast オプション検証 — 問題のあるパスを修正してください。

ビルド / 依存関係エラー

パッケージはまったくインストールできません — Doconut.NETStandard 26.8.0 は netstandard2.1 を対象としているため、NuGet は .NET Framework プロジェクトを拒否します。これは解決可能な復元エラーではありません：.NET Framework は netstandard2.1 を使用できません。代わりに Doconut.NETFramework パッケージを使用してください。

コンパイラ エラー CS1705、またはドキュメントを開く際の実行時エラー:

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

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

パッケージをバージョンアップした直後に大量のコンパイルエラーが発生 — これは予想通りです。26.8.0 は 26.7.0 とは異なる API 表面であり、互換性のある更新ではありません。エラーの多くは using 行がルートの Doconut 名前空間に移動したことによるものです。1つずつ修正するのではなく、.NET Standard 2.1 への移行 を実行してください。

最初のプレゼンテーション ファイルでの 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 参照は既成のエンドポイントを示しています。

レガシー文書が文字化けして表示される — コードページ エンコーディングはデフォルトでロードされません。起動時に一度だけ追加してください:

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 を提供しています。これはこのスイッチを最後にサポートしたバージョンです。

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

本番リリース時の典型的な驚き: アクティブな一時ライセンスはすべての機能を付与しますが、購入したライセンスは購入した機能だけを付与します。検索や注釈バンドルは、対応する機能がない場合に消失することがあります。十分でない非一時ライセンスで登録されたコンバータや 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、ライセンス診断出力を添えてサポートに連絡してください。

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