トラブルシューティング
一般的なエラーを診断する
以下のメッセージはすべて Doconut が生成する文字列で、症状別に整理されています。エラーを見つけて、修正を適用してください。
ビューアが何も表示しない
ビューア領域が空で、ブラウザコンソールに /doconut-res/... に対する 404 が多数表示されます
UseDoconutResources() が欠落しているか、UseDoconut() の後に配置されています。パイプラインの最初に配置する必要があります。
ビューアが The viewer handler could not be reached (no response). を報告します
リクエストは応答を受け取っていません。一般的な原因は、BasePath が / で始まっていることです:'/doconut' が //doconut/DocImage.axd に変わり、別のホストへのリクエストになります。先頭のスラッシュ(BasePath: 'doconut')を除いて記述してください。
ビューアが Please make sure your middleware is configured. を報告します
ページエンドポイントは 404 と応答しました:UseDoconut() がクライアントの BasePath が指す場所にマウントされていません。app.Map("/doconut", branch => branch.UseDoconut()) を使用すると、クライアントは BasePath: 'doconut' を使用します。
HTTP 500 とともに:
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 アプリはすでに登録されています)。
ページ領域に表示されるエラー画像(テキスト):
You Are Not Authorized To View This Page.トークンが別のブラウザセッションで開かれました。典型的な原因は、セッションクッキーがページリクエストに届いていないことです(クロスオリジン設定、SameSite ポリシー、クッキー保存なしの API クライアントなど)、またはアプリが再起動した(新しいセッションキー)。これは設計どおりに機能しているセキュリティ層です — Core Concepts → Sessions & Security を参照してください。拒否はステータス 200 で提供される画像であるため、ステータスコードのみをチェックするモニタはそれをページとしてカウントします。
エラー画像(テキスト):
Document session not found. Please re-open document.トークンが期限切れです(スライディングウィンドウ、デフォルト 60 分 — DocOptions.TimeOut)またはセッションが閉じられました。新しいトークンを取得するためにドキュメントを再度開いてください。
ドキュメントのオープンに失敗する
LicenseException が拒否メッセージとともに — ライセンスファイルは見つかりましたが、拒否されました(署名が無効、改ざん、ブラックリスト登録、またはライセンスのバージョン/更新ウィンドウ外のビルド)。この状態はウォーターマークに降格するのではなく、オープンをブロックします(即時失敗)。理由は License.RejectionMessage を参照してください。
LicenseException:
This document type requires the 'Dicom' plugin license.この拡張子はプラグイン(ここでは DICOM)だけで処理されます。プラグインは登録されていますが、機能を許可するライセンスがなくなっています — 通常、アプリ起動後に期限切れとなった一時ライセンスです。機能を許可するライセンスをインストールし、IDoconutLicenseService 上の IsCapabilityGranted(LicenseCapability.Dicom) を確認してください。非一時的な権利が欠如または不足している場合は、通常は AddDoconut() の段階で早期に失敗します。
FormatNotSupportedException:
Document format '<extension>' is not supported.組み込み、プラグイン、またはカスタムのいずれのビューアもその拡張子をサポートしていません。サポートされているフォーマット一覧を確認してください;独自のフォーマットの場合、DoconutOptions.RegisterViewer で追加できます。
InvalidDataException — ファイル内容が破損しているか、拡張子と一致しません(例:名前を変更したファイル)。オープンする前にアップロードを検証してください。
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Converter プラグインを登録せずに DocumentConverter を解決しました。
起動失敗
InvalidOperationException が AddPlugin を介して登録されたプラグインに言及 — 現在の非一時的ライセンスはそのプラグイン機能を付与しません。登録を削除するか、機能を付与するライセンスをインストールしてください。ライセンスが欠如している場合やレガシー TRIAL ファイルはプラグイン機能を付与しません。
ArgumentException から AddDoconut():
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、またはドキュメントを開く際の実行時エラー:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'プロジェクトが System.Text.Json または System.Text.Encodings.Web を Doconut.NET8 が宣言した 8.0.x の依存関係より下位に固定しています。ダウングレードを削除し、NuGet にパッケージグラフを復元させてください(System.Text.Json 8.0.5 と System.Text.Encodings.Web 8.0.0)。
出力が正しくない
ページに透かしが付いています — アプリは評価モードです:ライセンスファイルが見つからない、期限切れの一時ライセンス、または無効なドメインです。アクティブな一時ライセンス下では、プラグイン出力のみが透かし付きになります。有料ライセンスの購読日以降にリリースされたビルドは透かしが付かず、開くと LicenseException がスローされます。IDoconutLicenseService を確認してください(License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage)— Licensing ページの IDoconutLicenseService 参照が既成のエンドポイントを示しています。
レガシー文書が文字化けして表示されます — .NET 8 ではコードページエンコーディングがデフォルトでロードされません。起動時に一度追加してください:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);フォントが誤っている、または代替フォントが使用されています — サーバーにドキュメントのフォントがありません。インストールするか、FontFolders(WordConfig/PptConfig 上)をフォントが格納されたフォルダーに指すようにしてください。Linux の場合は下記をご覧ください。
画像注釈はビューアに表示されますが、エクスポートでは「Image blocked」ボックスが表示されます — 画像のホストがプライベートまたはループバックアドレスであり、サーバーが取得を拒否しています。注釈
Linux
任意のドキュメントを開くと次のエラーが発生します:
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.フォント設定ライブラリをインストールしてください: apt-get install -y libfontconfig1(RHEL/Fedora の場合は fontconfig)。インストール を参照してください。
任意のドキュメントを開くと次のエラーが発生します:
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.アプリケーションが新しい SkiaSharp を直接または他のライブラリ経由で参照しています。SkiaSharp.NativeAssets.Linux をその SkiaSharp と同じバージョンで追加してください。
任意のドキュメントを開くと次のエラーが発生します:
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.ホストはサポートされているプラットフォームではありません。Alpine やその他の musl ベースのディストリビューションはサポートされていません。Debian または Ubuntu ベースのイメージを使用してください。
テキストが Windows より太くまたは細く表示されたり、改行位置が異なる — ドキュメントのフォントがインストールされていないため、Doconut は最も近いインストール済みフォントを使用します。メトリック互換フォントをインストールしてください(Arial、Times New Roman、Courier New 用の fonts-liberation、Calibri と Cambria 用の fonts-crosextra-carlito と fonts-crosextra-caladea)。あるいは、独自のライセンスフォントを /usr/share/fonts/ にコピーし、fc-cache -f を実行してください。アジア文字が空白のボックスとして表示される場合は fonts-noto-cjk が必要です。
評価では機能したが、本番では無効
典型的な本番稼働時の驚きは:アクティブな Temporary ライセンスはすべての機能を付与します; 購入したライセンスは、購入したものだけを付与します。Search と annotation のバンドルは、機能が存在しない場合に消えることがあります。 不十分な非 Temporary ライセンスで登録された 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 ライセンスとは別ですので、両方を確認してください。- ページは
objViewer.Search(...)の戻り値を読み取ります — カウントは第3引数のコールバックで渡されます。
まだ行き詰まっていますか?
最小の Quick Start アプリで問題を切り分けてください。そこで再現する場合は、ドキュメント、Program.cs、およびライセンス診断出力を添えてサポートに連絡してください。
このページは役に立ちましたか?