トラブルシューティング

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

以下のメッセージはすべて 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 とともに:

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 を参照してください。拒否はステータス 200 で提供される画像であるため、ステータスコードのみをチェックするモニタはそれをページとしてカウントします。

エラー画像(テキスト):

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)だけで処理されます。プラグインは登録されていますが、機能を許可するライセンスがなくなっています — 通常、アプリ起動後に期限切れとなった一時ライセンスです。機能を許可するライセンスをインストールし、IDoconutLicenseService 上の 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>().

Converter プラグインを登録せずに DocumentConverter を解決しました。

起動失敗

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'

プロジェクトが 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 ではコードページエンコーディングがデフォルトでロードされません。起動時に一度追加してください:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

フォントが誤っている、または代替フォントが使用されています — サーバーにドキュメントのフォントがありません。インストールするか、FontFolders(WordConfig/PptConfig 上)をフォントが格納されたフォルダーに指すようにしてください。Linux の場合は下記をご覧ください。

画像注釈はビューアに表示されますが、エクスポートでは「Image blocked」ボックスが表示されます — 画像のホストがプライベートまたはループバックアドレスであり、サーバーが取得を拒否しています。注釈

Linux

任意のドキュメントを開くと次のエラーが発生します:

text
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)。インストール を参照してください。

任意のドキュメントを開くと次のエラーが発生します:

text
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 と同じバージョンで追加してください。

任意のドキュメントを開くと次のエラーが発生します:

text
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、およびライセンス診断出力を添えてサポートに連絡してください。

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