ファイルアップロードの失敗:再試行前の原因特定
アップロードに失敗したら、ブラウザーの Network パネルを開き、小さな有効なテストファイルで一度再現します。アップロードリクエストを探し、レスポンスを調べてサーバーログと照合してから、制限の変更や再試行の追加を検討します。このガイドは、既存の Web アップローダーをデバッグする開発者向けです。原因を確認するには、リクエスト処理コードとログへのアクセスが必要です。
失敗した試行の記録
アップロード前に DevTools を開きます。送信時にページが遷移する場合は Preserve log を有効にし、リクエストの URL、メソッド、ステータス、ペイロード、レスポンス、タイミングを調べます。これらの情報の場所は、Chrome の Network パネルガイドで確認できます。アップロード URL の取得、バイトの転送、アップロードの確定はそれぞれ別に失敗し得るため、アップロードフローのすべてのリクエストを確認します。
時刻、ファイルのサイズと種類、ステータス、サービスが返したリクエスト ID を記録します。その ID でプロキシログとアプリケーションログを照合します。ID がない場合は、タイムスタンプ、ルート、テストアカウントを使います。共有するレポートには、Cookie、認証ヘッダー、署名付き URL、ファイルの内容を含めないでください。
失敗するファイルを、同じサポート対象形式の小さなファイルと比較します。両方とも失敗するなら、サイズだけでは原因を説明できません。大きなファイルだけが失敗する場合は、制限なのかリクエストの中断なのかを判断する前に、サイズとタイミングの証拠を調べます。
失敗したレイヤーの特定
ステータスは手がかりとして扱います。リクエストを拒否したコンポーネントは、レスポンスと対応するログで特定します。プロキシとアプリケーションが同じステータスを返す場合があります。
| 観測結果 | 次の確認事項 |
|---|---|
| アップロードリクエストが表示されない | クライアントの検証、ファイル選択、JavaScript の例外。複数段階のフローでは、先行するリクエストの失敗も確認します。 |
401 または 403 | 認証、アップロード権限、認証情報の期限切れ、CSRF 検証。サービスのエラーコードを確認します。 |
413 | プロキシのリクエストボディ制限とアプリケーションのファイル制限。拒否を記録したコンポーネントを探します。 |
400、415、または 422 | 想定されるフィールド名、リクエストのエンコーディング、アプリケーションのファイル検証結果。 |
fetch() が読み取れるレスポンスなしで拒否される | ブラウザーコンソールの詳細、CORS、接続エラー、キャンセル。サーバーがリクエストを受信したか確認します。 |
500、502、503、または 504 | サーバーログ内のアプリケーションエラー、上流サービスの可用性、タイムアウト、ストレージエラー。 |
2xx レスポンスはあるが、使えるファイルがない | レスポンスの内容、リダイレクト、確定処理、処理ジョブがあればそのステータス。 |
これらは調査の進め方であり、ステータスと原因の普遍的な対応表ではありません。たとえば、413 はリクエストの内容が大きすぎることを示し、503 はサービスが一時的に利用できないことを示します。ディスクの空き容量不足を特定するものではありません。HTTP ステータスの定義を参照してください。
コードで HTTP の失敗を見落とさないための処理
fetch() は HTTP エラーレスポンスでも解決されます。Promise の拒否と、ok: false を持つレスポンスは異なる観測結果です。ボディを解析する前に response.ok を確認します。そうしないと、プロキシの HTML エラーページが、紛らわしい JSON 解析エラーになることがあります。
既存の multipart アップロードハンドラーに対し、次の TypeScript ヘルパーはこの違いを維持します。選択されたファイルとハンドラーの URL を受け取り、file という名前のフィールドを一つ送信します。API の仕様に合う場合にのみ使用し、リクエストを調整するときも、アプリケーションに必要な認証と CSRF 処理は残してください。ハンドラーはあらかじめ稼働している必要があります。
async function uploadForDiagnosis(
file: File | undefined,
url: string,
): Promise<Response | undefined> {
if (file === undefined) return
const body = new FormData()
body.append('file', file)
const response = await fetch(url, { method: 'POST', body })
if (!response.ok) {
throw new Error(`Upload returned HTTP ${response.status}`)
}
return response
}
既存の送信ハンドラーから、選択された File とアップロード URL を渡し、結果を await して、そのハンドラーで拒否を処理します。未選択なら何も送信しませんが、空のファイルではリクエストを送信します。Upload returned HTTP 413 は、読み取れる HTTP レスポンスが届いたことを意味します。ブラウザーのネットワークエラーや CORS エラーでは、fetch() 自体が拒否され、その拒否はこのヘルパーを通過します。ヘルパーは再試行をスケジュールしません。返されたレスポンスにも、API の通常の成功検証が必要です。たとえば、ログインへのリダイレクトが 200 で終わっても、ファイルが受け入れられた証拠にはなりません。
この FormData リクエストでは、Content-Type を手動で設定しないでください。ブラウザーが multipart の境界を設定するため、ヘッダーを上書きすると解析できなくなることがあります。既存のアップロードハンドラーの処理中は、重複送信を無効にしておきます。
アップロードを拒否したコンポーネントの変更
リクエスト経路に沿ったサイズ制限の追跡
小さなファイルは成功し、大きなファイルでは 413 が返るとします。プロキシに拒否のログがあり、アプリケーションに対応するリクエストがなければ、まずプロキシを調べます。ログがないことを証拠とする前に、アプリケーションのリクエストログが有効になっていることを確認します。
NGINX では、client_max_body_sizeがリクエストボディを制限し、http、server、location の各レベルで設定できます。実際のアップロードルートに適用される設定を確認します。multipart リクエストには、ファイル以外にフィールドと境界も含まれるため、リクエストボディの上限には許可するファイルサイズ以上の余裕が必要です。アプリケーションの上限を引き上げても、その手前のプロキシの制限は解除できません。
製品の文書に記載された上限ならそのファイルを受け入れるはずの場合は、ストレージとリソースの予算内で、拒否しているレイヤーを調整します。そうでなければ上限を維持し、UI で説明します。元のファイル、許容サイズの直下のファイル、上限を超えるファイルで再テストします。最後のファイルは引き続き拒否されるべきです。
アプリケーションの拒否理由の確認
不正なリクエストや未対応ファイルを示すレスポンスでは、リクエストをハンドラーの仕様と比較します。想定しているのは、file という名前の multipart フィールド、別のフィールド名、それとも生のボディでしょうか。リクエストに必要なメタデータは含まれているでしょうか。レスポンスやログで不一致を特定するまでは、エンコーディングの切り替えや拡張子の変更をしないでください。
ファイルの実際の形式が未対応なら、対応している形式のソースを選ぶか、適切なツールで変換します。.exe を .jpg に変更しても、内容は変換されません。有効と確認済みのファイルで再テストし、許可されないファイルも拒否確認用に残しておきます。
CORS と接続障害の切り分け
ブラウザーの一般的な fetch エラーだけでは原因を特定できません。コンソールの具体的なエラーを、Network パネルやサーバーログと併せて調べます。
OPTIONSプリフライトが失敗する場合は、サーバーで許可するオリジン、メソッド、リクエストヘッダーを確認します。ブラウザーはアップロードを送信する前に停止することがあります。- アップロードがサーバーに届いても、レスポンスに必要な CORS ヘッダーがなければ、JavaScript はそのレスポンスを読み取れません。サーバーはすでにファイルを受け入れている可能性があります。再試行前に保存状態を確認します。
- ブラウザーが接続エラーや証明書エラーを報告する場合は、その接続を調査します。コードがリクエストを中止した場合は、引き金となったキャンセルやタイムアウトを探します。
レスポンスを返すサーバーで、エラーレスポンスも含めて CORS を設定します。認証情報付きのクロスオリジンリクエストには、明示的に許可するオリジンと適切な認証情報設定が必要です。* では代用できません。MDN の CORS ガイドに、プリフライトとレスポンスの確認処理が説明されています。元のブラウザーオリジンから、元の認証条件で再テストします。cURL リクエストが成功しても、ブラウザーの CORS が機能する証明にはなりません。
対処として mode: 'no-cors' を使わないでください。これは不透明なレスポンスを生成し、コードからステータスやボディを調べられなくなります。受け入れられるアップロードと意図的に拒否されるアップロードの両方を再テストします。どちらのレスポンスも、許可されたオリジンから読み取れる必要があります。
サーバーエラーから失敗した操作への追跡
5xx レスポンスには、対応するサーバー側のエラーが必要です。リクエストの解析、一時ファイルへの書き込み、最終オブジェクトの保存、後続処理の実行のどこで失敗したのかを特定します。ファイルシステムに保存する場合は、空き容量、クォータ、実際の保存先パス、サービスアカウントの権限を調べます。一時ストレージも確認します。最終保存先のディレクトリが書き込み可能でも、アップロードパーサーがデータをスプールできるとは限りません。
根本のエラーに基づいて対処を選びます。たとえば、Node の
EACCES と ENOENT のエラーでは、権限エラーとパスの欠落を区別できます。該当するパスやサービスの権限を修正してから、同じアップロードを繰り返し、保存されたバイトを検証します。権限の問題を隠すために、アップロードディレクトリを誰でも書き込める状態にしないでください。ゲートウェイが上流サービスを利用できないと報告する場合は、ディスク設定やタイムアウトを変更する前にアプリケーションの健全性を確認します。
中断が問題となる場合の再開可能なアップロードの導入
有効なアップロードが機能するようになった後も接続の中断が繰り返される場合は、再開可能なアップロードを導入する理由になります。tusでは、互換性のあるサーバーを使い、クライアントが保存済みのオフセットを問い合わせて、その位置から続行できます。ブラウザー側でファイルをチャンクに分割するだけでは、オフセット、保存、完了について、このような合意は得られません。
再開機能では、無効なファイル、リクエストの拒否、CORS 設定、ストレージの枯渇は解決しません。導入する場合は中断と復旧をテストし、完成したファイルを元のファイルと比較します。tus の実装一覧を使い、互換性のあるクライアントとサーバーを選びます。
安全対策を維持した修正の検証
元の失敗ケースを再実行してから、有効な小さなファイルと、意図的に許可対象外としたファイルを試します。想定どおりの HTTP レスポンス、アプリケーションの受け入れ結果、保存されたファイルまたは最終処理結果を確認します。内容を変更しないアップロードでは、ダウンロードしたバイトやチェックサムを元のファイルと比較します。進捗バーの完了が示すのは、そのバーが測定している転送段階だけです。
UI で先に検証していても、サーバー側のサイズ検証と内容検証は維持します。ファイル名と申告された MIME タイプは信頼せず、保存名を生成し、アクセスを制限します。ファイルの種類とリスクに応じて、セキュリティスキャンやコンテンツの無害化を適用します。これらの対策は、OWASP のファイルアップロードガイダンスに説明されています。有用なエラーは、変更すべき点をユーザーに伝え、サポートにリクエスト ID を提供する一方、内部パス、スタックトレース、認証情報はレスポンスに含めません。
