Fessのストレージ画面でファイルが見つからないとき、バケットが空なのか、認証や接続に失敗しているのかは区別したいところです。S3・GCSストレージプラグインでは、一覧取得中の例外を捕まえて空または途中までの一覧を返す経路がありました。そのため、取得失敗が正常な「0件」に見えることがあります。
この動作を改善するS3側のPR #4とGCS側のPR #6が提案されています。2026年10月17日の確認時点では両方とも未マージです。以下は修正案の説明であり、Fess 15.9.0や公開済みプラグインに反映済みという案内ではありません。
一覧取得の失敗を呼び出し元へ伝える
修正案では、listObjects内で発生した例外をStorageExceptionとして呼び出し元へ伝えます。メッセージには対象のバケットとprefixが入り、元の例外も原因として保持します。GCSでは一覧ページの取得だけでなく、結果を走査している途中の失敗も対象です。
Fess 15.9.0側の管理処理には、例外を受けてストレージアクセスエラーにする経路があります。プラグイン側で例外を握りつぶさなければ、管理画面・管理APIで正常な空一覧と区別できるようになります。
ただし、すべてのエラーが新しい動作になるわけではありません。S3のNoSuchBucketExceptionは従来どおりINFOログを記録し、空の一覧を返す扱いが残ります。GCSの修正案は、存在しないバケット等の取得例外もエラーとして伝えます。S3とGCSで「バケットがない」場合の動作は揃っていません。
空の一覧が返る場合に確認すること
この修正で新しい有効化設定は追加されません。利用には、対象のストレージ種類に合うプラグイン、バケット、認証情報、接続先の設定が必要です。修正を試す場合は、対応PRを含むプラグインを検証環境へ導入し、Fess本体との互換性も確認してください。未マージの修正が既存環境へ自動適用されることはありません。
既存環境で一覧が空なら、まず次を確認します。
- ストレージ種類とプラグインが一致しているか。プラグインを導入・変更した場合はFessを再起動したか。
- エンドポイント、バケット名、リージョンまたはプロジェクト、認証情報が対象環境に合っているか。
- 実行環境から接続先へ到達でき、オブジェクト一覧を取得する権限があるか。
- 指定したprefixが正しいか。サブディレクトリ相当のprefixを指定していれば、別の場所にあるオブジェクトは表示されない。
Fess側でプラグインが見つからない、認証情報が未設定といった初期化エラーを表示できても、その後のプラグイン内部の一覧取得失敗まで常に表示できるとは限りません。修正前の環境では「0件、成功」という応答だけで接続正常と判断しないようにします。
件数制限やダウンロードの問題とは分けて考える
正常に取得できた空バケットは、修正後も空の一覧です。また、Fess 15.9.0のstorage.max.items.in.pageの初期値は1000で、このPRは上限やページングを変更しません。画面に見える一覧だけでバケット内の全オブジェクト数を判断することはできません。
対象はオブジェクト一覧の失敗通知です。ダウンロード、アップロード、削除の動作や、接続可否を調べる別のメソッドを一括で変える修正ではありません。自動再試行や認証情報の修復も追加されません。
導入を検討する際は、正常な空バケット、オブジェクトのあるprefix、接続先へ到達できない状態をそれぞれ確認すると、0件と失敗を区別できるかを確かめやすくなります。S3の存在しないバケットの例外扱いも、運用監視の条件に含めてください。