トラブルシューティング
一般的なエラーを診断する
以下のメッセージはすべて 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 クライアント)、またはアプリが再起動したこと(新しいセッションキー)です。これは設計通りに機能しているセキュリティ層です — コアコンセプト → セッションとセキュリティ を参照してください。拒否はステータス 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>().コンバータプラグインを登録せずに 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.Fail-fast options validation — 問題のあるパスを修正してください。
ビルド / 依存関係エラー
コンパイラエラー CS1705、またはドキュメントを開く際の実行時エラー:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'プロジェクトが System.Text.Json または System.Text.Encodings.Web を 8.0.x 未満に固定しています。Doconut.NET6 が宣言した依存関係です。ダウングレードを削除し、NuGet にパッケージグラフを復元させてください(System.Text.Json 8.0.6 および System.Text.Encodings.Web 8.0.0 がパッケージで宣言されています)。
出力が正しくない
ページに透かしが付く — アプリが評価版状態です:ライセンスファイルが見つからない、期限切れの一時ライセンス、または無効なドメインです。アクティブな一時ライセンス下では、プラグインの出力のみが透かし付与されます。有料ライセンスのサブスクリプション日以降にビルドされたものは透かしが付かず、開くと LicenseException がスローされます。IDoconutLicenseService(License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage)を確認してください — ライセンスページの IDoconutLicenseService 参照に完成済みエンドポイントが示されています。
レガシードキュメントが文字化け — .NET 6 ではコードページエンコーディングがデフォルトで読み込まれません。起動時に一度だけ追加してください:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);フォントが間違っている、または置き換えられている — サーバーにドキュメントのフォントがありません。フォントをインストールするか、FontFolders(WordConfig/PptConfig 上)をフォントが格納されたフォルダーに指すようにしてください。Linux の場合は下記をご参照ください。
画像アノテーションがビューアには表示されるが、エクスポートでは「画像がブロックされました」ボックスになる — 画像のホストがプライベートまたはループバックアドレスであり、サーバーが取得を拒否しています。詳しくは 注釈 をご覧ください。
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 と同じバージョンの SkiaSharp.NativeAssets.Linux を追加してください。
任意のドキュメントを開くと次のエラーが発生:
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 バンドルは消えることがあります。十分でない非一時的ライセンスの Registered 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、およびライセンス診断出力を添えてサポートに連絡してください。
このページは役に立ちましたか?