aws-samples / aws-samples/generative-ai-use-cases
添付が失敗しても原因が利用者に伝わらない(ValidationException が全て UNKNOWN_ERROR に落ちる)
- Dominant language
- TypeScript
- Stars
- 1.4k
- Forks
- 433
- Avg merge
- 2h 35m
- Merged PRs (30d)
- 1
Description
### 概要
チャットユースケースで添付が失敗したとき、利用者には常に同じ文言しか表示されず、何が原因か判別できません。`ValidationException` が全て `UNKNOWN_ERROR` に分類されるためです。
原因が具体的に分かれば利用者自身で回避できるケースが大半のため、エラーコードを細分化して i18n 文言を出せるようにしたいです。
確認バージョン: v5.5.0 / main
### 現状の挙動
`packages/cdk/lambda/utils/bedrockApi.ts` の catch が 3 分岐しかありません。
```ts
if (e instanceof ThrottlingException || e instanceof ServiceQuotaExceededException) {
yield streamingChunk({ text: '', stopReason: 'error', errorCode: 'THROTTLING' });
} else if (e instanceof AccessDeniedException) {
yield streamingChunk({ text: '', stopReason: 'error', errorCode: 'ACCESS_DENIED' });
} else {
yield streamingChunk({ text: '', stopReason: 'error', errorCode: 'UNKNOWN_ERROR' });
}
```
添付起因の失敗はすべて `ValidationException` なので、漏れなく `else` に落ちます。結果として利用者には次の文言だけが表示されます。
```yaml
# packages/web/public/locales/translation/ja.yaml
UNKNOWN_ERROR: エラーが発生しました。再度お試しいただくか、管理者にお問い合わせください。
```
同じ 3 分岐が `bedrockAgentApi.ts` と `bedrockKbApi.ts` にも重複しています。
### 実際に発生しているエラーの内訳
自社環境の本番 Lambda ログを 7 日分集計した結果です(合計 494 件)。
| 件数 | Bedrock が返しているエラー |
|---|---|
| 232 | `The document file name can only contain alphanumeric characters, whitespace characters, hyphens, parentheses, and square brackets. The name can't contain more than one consecutive whitespace character.` |
| 85 | `Messages can't contain duplicate document names. Rename the document and retry your request.` |
| 50 | `You can't include more than 5 documents in a request. Reduce the number of documents and retry your request.` |
| 34 | `The model returned the following errors: messages: text content blocks must be non-empty` |
| 20 | `Unsupported MIME type: application/x-bat. Retry your request with a supported file type: xlsx, txt, pdf, csv, md, doc, html, xls, docx` |
| 19 | `The model returned the following errors: prompt is too long: 1011576 tokens > 1000000 maximum` |
| 3 | `The maximum document size is 4.5 MB. Reduce the size of your document and retry your request.` |
| 51 | その他 |
**Bedrock 側は十分に具体的な理由を返しています。**それが利用者に一切届いていない状態です。
### 利用者側で何が起きているか
添付ファイルの保存先を調べたところ、**同一ファイルが 3〜9 回連続で再アップロードされている記録**が多数ありました。ファイルサイズを削って再挑戦した形跡もあります。原因が表示されないため、利用者は当て推量でリトライし、最終的に諦めています。
上記のうち大半は、理由さえ分かれば利用者自身が数十秒で回避できるものです(ファイル名を変える、添付を減らす、形式を変える等)。
### 提案
`StreamingErrorCode` にコードを追加し、`ValidationException` のメッセージから分類します。
```ts
// packages/types/src/protocol.d.ts
export type StreamingErrorCode =
| 'THROTTLING'
| 'ACCESS_DENIED'
| 'INVALID_FILE_NAME'
| 'DUPLICATE_FILE_NAME'
| 'TOO_MANY_DOCUMENTS'
| 'DOCUMENT_TOO_LARGE'
| 'IMAGE_TOO_LARGE'
| 'UNSUPPORTED_FILE_TYPE'
| 'CONTEXT_TOO_LONG'
| 'EMPTY_MESSAGE'
| 'UNKNOWN_ERROR';
```
分類は 3 箇所の catch で共用できるよう、共通関数に切り出すのがよいかと思います。
```ts
const classifyValidationError = (message: string): StreamingErrorCode => {
if (/document file name can only contain/.test(message)) return 'INVALID_FILE_NAME';
if (/duplicate document names/.test(message)) return 'DUPLICATE_FILE_NAME';
if (/more than 5 documents/.test(message)) return 'TOO_MANY_DOCUMENTS';
if (/maximum document size is/.test(message)) return 'DOCUMENT_TOO_LARGE';
if (/image exceeds .* maximum/.test(message)) return 'IMAGE_TOO_LARGE';
if (/Unsupported MIME type/.test(message)) return 'UNSUPPORTED_FILE_TYPE';
if (/prompt is too long|Input is too long/.test(message)) return 'CONTEXT_TOO_LONG';
if (/text content blocks must be non-empty/.test(message)) return 'EMPTY_MESSAGE';
return 'UNKNOWN_ERROR';
};
```
i18n 文言案(`ja`)です。
```yaml
INVALID_FILE_NAME: ファイル名に使用できない文字が含まれています。全角スペース・連続する半角スペース・タブを取り除いて添付し直してください。
DUPLICATE_FILE_NAME: 同じ名前のファイルが複数含まれています。ファイル名を変更するか、重複を外して再度お試しください。
TOO_MANY_DOCUMENTS: 添付できる書類は5件までです。過去のやり取りに含まれる添付も件数に数えられるため、新しい会話を開始してお試しください。
DOCUMENT_TOO_LARGE: 書類は1ファイルあたり4.5MBまでです。
IMAGE_TOO_LARGE: 画像は1ファイルあたり3.75MBまでです。
UNSUPPORTED_FILE_TYPE: この形式のファイルには対応していません。
CONTEXT_TOO_LONG: 添付内容が大きすぎて読み込めません。行数やシート数を絞ってお試しください。
EMPTY_MESSAGE: メッセージ本文が空です。質問や指示を入力してください。
```
`TOO_MANY_DOCUMENTS` は「履歴の添付も件数に含まれる」ことを明記するのが要点かと思います。1 回に 3 件しか添付していないのに 5 件超で拒否されるため、現状の作りでは利用者が理由を推測できません。
### 設計上の留意点
- AWS 側のエラー文言が変わると文字列マッチが外れます。**`UNKNOWN_ERROR` のフォールバックは必ず残す**前提です
- `ValidationException` の生メッセージをそのまま画面に出すのは避けたいです。英語であることに加え、`messages.2.content.0.image...` のような内部構造が露出します
- 既存の `PAYLOAD_TOO_LARGE` はフロント側の事前チェック用で、サーバ側のコード体系とは別系統です
### 関連
最頻出の `INVALID_FILE_NAME`(232 件)については、GenU 側のサニタイズ処理に原因があります。別 Issue に切り出しました → #1671
ただしそちらを修正しても、本 Issue の他の 7 分類は残ります。
Contributor guide
Research direction
Start with the catch blocks in packages/cdk/lambda/utils/bedrockApi.ts, bedrockAgentApi.ts, and bedrockKbApi.ts, then inspect StreamingErrorCode in packages/types/src/protocol.d.ts and the related entries in packages/web/public/locales/translation/ja.yaml. Trace how streaming error codes reach the UI and check existing error-handling tests. Done means recognized ValidationException cases receive localized codes across all three paths while unknown messages retain UNKNOWN_ERROR.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- api, backend, localization
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100