Posts

冒頭まとめ アクセスログに残る 499 は、Nginx が応答を返す前にクライアント側から接続が切られたことを示すコードです。HTTP の標準にはない Nginx 独自のコードで、相手はすでにいないため、利用者のブラウザにこのコードが表示されることはありません。つまり 499 は「エラー画面が出る問題」ではなく「ログにだけ現れる兆候」です。 原因は、クライアントが先に諦めた理由が何か、という問いに置き換えられます。典型は3つで、上流の応答が遅くクライアント側の制限時間が先に切れた、利用者が操作を中断した（画面を閉じた・再読み込みした）、Nginx の手前にいる中継役（ロードバランサーなど）や監視の仕組みが応答を待たずに切断した、のいずれかです。切り分けの鍵は処理時間の記録ですが、既定のログ形式には含まれないため、まず $request_time をログに加えるところから始めます。 エラーの概要 Nginx のソースコードには、499 を定義した箇所に説明が書かれています。要約すると、リクエストの処理中にクライアントが接続を閉じた場合を表すコードが HTTP には定義されていないため、応答ヘッダーを送ろうとする前にクライアントが接続を閉じていた状況を記録する目的で、独自のコードとして導入した、という内容です。 504 Gateway Timeout との対比で理解すると分かりやすいコードです。上流の応答が遅いとき、Nginx 側が待ちきれずに打ち切ればクライアントに 504 が返ります。Nginx がまだ待っている間にクライアント側が先に切れば、誰にも何も返らず、ログに 499 が残ります。同じ「遅い」という状況でも、どちらが先に諦めたかで記録が変わります。 診断上の重要な特徴が2つあります。第一に、499 はエラーログには info レベルでしか記録されません。エラーログの既定のレベルでは何も出力されないため、「アクセスログに 499 があるのにエラーログに手がかりがない」のは正常な動作です。第二に、既定では、クライアントの切断を検知した時点で Nginx は上流への接続も閉じます（この動作は後述の proxy_ignore_client_abort で変えられます）。ただし上流のアプリケーションが切断を検知しない作りの場合、応答の届け先がないまま処理だけが完走することもあります。 アクセスログには次のように記録されます。応答を送っていないため、送信バイト数が 0 になるのが典型です。 192.168.1.100 - - [09/Jul/2026:14:22:10 +0900] "POST /api/report HTTP/1.1" 499 0 "-" "python-requests/2.31.0" まず最初に：処理時間をログに出す 既定の combined 形式には、リクエストの処理にかかった時間が含まれません。499 の切り分けには時間の情報が不可欠なので、log_format に $request_time（リクエスト全体の処理時間）と $upstream_response_time（上流の応答にかかった時間）を加えます。どちらも公式ドキュメントに記載のある変数です。 http { log_format timed '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" "$http_user_agent" ' 'rt=$request_time urt=$upstream_response_time'; access_log /var/log/nginx/access.log timed; } 反映後に記録される 499 の行を見て、次のように読み分けます。 ...

冒頭まとめ Nginx の 413 Request Entity Too Large は、リクエスト本文の大きさが client_max_body_size の上限を超えたときに返されます。上限の既定値は 1MB と小さいため、ファイルのアップロード機能を作ると最初にぶつかりやすいエラーです。対処はほぼ client_max_body_size の調整に集約されますが、落とし穴が2つあります。1つは設定を書く場所で、より内側（location など）に別の指定があるとそちらが使われるため、書いたのに効かないという状況が起きます。もう1つは Nginx の先にいるアプリケーション側の上限で、Nginx の上限を上げるだけでは足りない場合があります。 必要な上限の値は推測しなくて済みます。Nginx が413を返したとき、エラーログに実際に送られようとしたバイト数が記録されるからです。まずエラーログを読み、実測値をもとに上限を決めます。 エラーの概要 413 は、リクエストの本文（ファイルのアップロード内容やフォームの送信内容）が、サーバーの受け入れ上限を超えたことを示すコードです。Nginx では client_max_body_size がこの上限を定めており、公式ドキュメントのとおり既定値は 1m（1MB）です。なお、HTTP の現行仕様（RFC 9110）ではこのコードの名称は Content Too Large に改められていますが、Nginx の既定エラーページの文言は「413 Request Entity Too Large」です。 注意すべき点として、公式ドキュメントには、ブラウザはこのエラーを正しく表示できない場合があるという注記があります。つまり利用者の画面では、413のページが出るとは限らず、送信が途中で失敗した・接続が切れた、といった413と分からない形で現れることがあります。アップロードだけが原因不明で失敗するという相談を受けたら、まずサーバー側のログで413が出ていないかを確認する価値があります。 アクセスログ（既定の combined 形式）には次のように記録されます。 192.168.1.100 - - [08/Jul/2026:11:20:15 +0900] "POST /upload HTTP/1.1" 413 183 "-" "Mozilla/5.0" まず最初に：エラーログを読む アクセスログで413を確認したら、同時刻のエラーログを見ます。 sudo grep "too large" /var/log/nginx/error.log | tail -10 client intended to send too large body: 15728640 bytes のような行があれば、Nginx 自身が client_max_body_size の検査で拒否しています。行末の数字が、実際に送られようとした本文のバイト数です（この例では15MB）。必要な上限をこの実測値から決められるので、原因1・2に進みます。チャンク転送（本文の大きさを事前に知らせない送り方）の場合は client intended to send too large chunked body という文言になります。 ...

エラーの概要 AWS S3 の AccessDenied エラーは、IAM ポリシーの不足、バケットポリシーの明示的な拒否設定、またはオブジェクトの ACL 設定によって、リソースへのアクセスが拒否されたときに発生します。認証情報は正常に認識されているものの、権限がない状態です。 実際のエラーメッセージ例 { "Error": { "Code": "AccessDenied", "Message": "Access Denied" } } An error occurred (AccessDenied) when calling the GetObject operation: Access Denied エラーメッセージの読み方： AccessDenied → HTTP ステータスコード 403 に相当。認証は成功したが権限がない Access Denied → リソースへのアクセスが拒否されていることを示すメッセージ リクエスト元の AWS アカウント・IAM ユーザー・ロールが、実行しようとしたアクション（s3:GetObject など）を許可されていない よくある原因と解決手順 原因1：IAM ポリシーで必要なアクションが許可されていない S3 バケットにアクセスするユーザー・ロール・サービスに対して、s3:GetObject、s3:PutObject などの必要な権限が付与されていない場合に発生します。特に新規に作成した IAM ユーザーや、特定のバケットに限定したアクセスに構成した際に起きやすいです。 Before（エラーが起きるコード）： { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::my-bucket" } ] } After（修正後）： { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::my-bucket" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": "arn:aws:s3:::my-bucket/*" } ] } ✅ 修正後の確認： ...

エラーの概要 AWS S3の NoSuchKey エラーは、指定したキー（オブジェクトパス）がバケット内に存在しないことを示すHTTP 404エラーです。このエラーが発生すると、GetObject、HeadObject、DeleteObject などのオブジェクト操作は失敗し、「The specified key does not exist.」というメッセージが返されます。一見すると「オブジェクトがないこと」を示していますが、実際には**キーの指定ミスやプレフィックスの誤り、大文字小文字の区別、削除済みオブジェクトの参照**など、複数の原因が絡むことが多いため、正確な診断が重要です。 実際のエラーメッセージ例 { "Error": { "Code": "NoSuchKey", "Message": "The specified key does not exist." }, "ResponseMetadata": { "HTTPStatusCode": 404, "HTTPHeaders": { "content-type": "application/xml" } } } エラーメッセージの読み方： "Code": "NoSuchKey" → S3が返すエラーコード。指定したキーがバケット内に存在しないことを示す "Message": "The specified key does not exist." → 詳細な説明。リクエストで指定されたオブジェクトがバケットに見つからなかったことを意味する "HTTPStatusCode": 404 → HTTP ステータスコード。リソースが見つからないことを示す標準的な応答 content-type: application/xml → S3がXML形式でエラーレスポンスを返していることを示す よくある原因と解決手順 原因1：キー名のスペルミス、パス区切りの誤り S3のキーは大文字小文字を区別し、ファイルパスの階層は スラッシュ（/） で区切られます。my-file.txt と my_file.txt は異なるキーであり、folder/file.txt と folder\file.txt も区別されます。これらのわずかなスペルミスや区切り文字の誤りが NoSuchKey エラーの最も一般的な原因です。 Before（エラーが起きるコード）： import boto3 s3 = boto3.client('s3') bucket_name = 'my-bucket' key = 'documents/my-file.txt' # キーが実際には 'documents/my_file.txt' で存在する response = s3.get_object(Bucket=bucket_name, Key=key) # NoSuchKey エラーが発生 After（修正後）： ...

エラーの概要 AWS S3 の NoSuchBucket エラーは、指定したバケット名が存在しない、またはそのバケットにアクセス権限がない場合に発生します。バケット名のスペルミスや、別のリージョンに存在するバケットを現在のリージョン設定で参照しようとした場合、あるいは既に削除されたバケットにアクセスしようとした場合に起こります。 実際のエラーメッセージ例 { "Error": { "Code": "NoSuchBucket", "Message": "The specified bucket does not exist" } } 別の環境では、以下のようなエラーが表示されることもあります。 An error occurred (NoSuchBucket) when calling the GetBucketLocation operation: The specified bucket does not exist エラーメッセージの読み方： NoSuchBucket → HTTP エラーコード：指定されたバケットが見つからないことを示す The specified bucket does not exist → メッセージ本文：バケットが存在していない、またはアクセス権限がない状態 GetBucketLocation operation → 実行しようとしていたオペレーション：この例ではバケットロケーション情報の取得 よくある原因と解決手順 原因1：バケット名のスペルミス バケット名を誤って入力していることが最も一般的な原因です。AWS S3 のバケット名は大文字小文字を区別し、グローバルに一意である必要があります。タイプミスや大文字・小文字の誤りがあると NoSuchBucket エラーが発生します。 Before（エラーが起きるコード）： aws s3 ls s3://my-data-bucket/ 実際のバケット名が my-data-bucket ではなく my-data-bucket-prod の場合、このコマンドは NoSuchBucket エラーを返します。 After（修正後）： aws s3 ls s3://my-data-bucket-prod/ ✅ 修正後の確認： ...

エラーの概要 GitLabの429エラー（Too Many Requests）は、GitLab APIのレート制限に達したことを示します。ユーザーまたはCI/CDパイプラインが短時間に許可された上限を超えるAPIリクエストを送信した場合に発生します。デフォルトのレート制限はエンドポイントやインスタンスの構成によって異なり、一般的には認証ユーザーは1分間に600リクエスト、未認証の場合は300リクエスト程度とされていますが、パッケージレジストリAPIなど特定のエンドポイントではより高い制限が適用される場合もあります。 実際のエラーメッセージ例 GitLab APIレスポンス： { "message": "429 Too Many Requests", "retry_after": 60, "ratelimit_limit": 600, "ratelimit_remaining": 0, "ratelimit_reset": 1699564800 } curlコマンドでのレスポンス： $ curl -H "PRIVATE-TOKEN: <your-access-token>" https://gitlab.example.com/api/v4/projects HTTP/1.1 429 Too Many Requests RateLimit-Limit: 600 RateLimit-Remaining: 0 RateLimit-Reset: 1699564800 Retry-After: 60 {"message":"429 Too Many Requests"} よくある原因と解決手順 原因1：短時間に多数のAPIリクエストを送出する処理 スクリプトやツールが迅速に連続したAPIコールを実行する際、GitLabのレート制限に即座に到達します。例えば、多数のプロジェクトやグループのメタデータを一括取得する場合、ループ処理で制限を超えやすくなります。 解決策：ページング機能を使用して効率的に取得する import requests import time TOKEN = "<your-access-token>" GITLAB_URL = "https://gitlab.example.com" headers = {"PRIVATE-TOKEN": TOKEN} # ページング機能を使用して効率的に取得 page = 1 while True: response = requests.get( f"{GITLAB_URL}/api/v4/projects", headers=headers, params={"page": page, "per_page": 100} ) if response.status_code == 429: reset_time = int(response.headers.get("RateLimit-Reset", 0)) current_time = int(time.time()) wait_seconds = reset_time - current_time print(f"Rate limit hit. Waiting {wait_seconds} seconds...") time.sleep(max(wait_seconds + 1, 0)) continue if response.status_code != 200: break for project in response.json(): print(f"Project: {project['name']}") if "next" not in response.links: break page += 1 原因2：CI/CDパイプラインが短時間に大量のAPIコールを実行している GitLabのCI/CDパイプラインで複数のジョブが並行実行される場合、各ジョブが独立してAPIを呼び出すと累積的にレート制限に達します。特に、依存関係の解決やアーティファクトダウンロードで多数のAPI呼び出しが発生する環境では顕著です。 ...

エラーの概要 GitLabの500エラーは、GitLabサーバー側で予期しない内部エラーが発生したことを示します。クライアント側の問題ではなく、GitLabのインフラストラクチャまたはアプリケーションレイヤーで何らかの処理に失敗した状態です。このエラーが発生すると、リポジトリーへのアクセス、プッシュ、マージリクエストの操作など、あらゆるGitLab機能が一時的に利用できなくなります。 実際のエラーメッセージ例 ブラウザでGitLabにアクセスした際の表示： 500 Internal Server Error An internal server error occurred. GitLab APIを呼び出した際のレスポンス： { "message": "500 Internal Server Error", "status": 500 } ターミナルからgit操作を実行した際のエラー： $ git push origin main fatal: unable to access 'https://gitlab.example.com/project.git/': The requested URL returned error: 500 よくある原因と解決手順 原因1：GitLabインフラの一時的な障害 GitLabのサーバーインフラストラクチャ側で一時的な障害が発生している場合、リクエストを処理できず500エラーが返却されます。これはデータベース接続の喪失、メモリ不足、ディスク容量の枯渇、または主要サービス（Sidekiq、Puma等）のクラッシュなど、複数の要因が考えられます。 解決手順： # まずstatus.gitlab.comで障害状況を確認する curl -s https://status.gitlab.com/api/v2/status.json | jq '.status' # WebUIで直接確認することもできる # https://status.gitlab.com にアクセスして「All Systems Operational」を確認 # 数分待機してから再試行する sleep 300 git push origin main GitLabの障害情報は status.gitlab.com で公開されています。ここで「All Systems Operational」と表示されていれば、インフラレベルの障害ではなく、個別リポジトリーやアカウント固有の問題である可能性が高くなります。 原因2：リポジトリのGitオブジェクト破損 GitLab内のリポジトリーが保存されているディスク上のGitオブジェクトが破損した場合、リポジトリーの読み書き処理で500エラーが発生します。これはハードウェア障害、不正なシャットダウン、ファイルシステムエラーなどに起因することがあります。 解決手順： ...

エラーの概要 GitLabの404エラーは、指定したプロジェクト・マージリクエスト・ファイルなどのリソースが見つからないことを意味します。API呼び出しやWebUIでのアクセス時に発生し、プロジェクトの存在確認、アクセス権限、リソースパスの誤入力などが主な原因です。プロジェクトが削除された、URLエンコーディングが正しくない、トークンの権限が不足している場合にも表示されます。 実際のエラーメッセージ例 GitLab API経由でのレスポンス： { "message": "404 Not Found" } curlコマンドでの出力： $ curl -H "PRIVATE-TOKEN: <your-token>" "https://gitlab.com/api/v4/projects/wrong-namespace%2Fproject-name" {"message":"404 Not Found"} WebUIでのブラウザ表示： 404 Not Found The page you're looking for could not be found. Python requests ライブラリでのエラー： import requests response = requests.get( "https://gitlab.com/api/v4/projects/invalid-path", headers={"PRIVATE-TOKEN": "<your-token>"} ) print(response.status_code) # 404 よくある原因と解決手順 原因1：プロジェクトIDまたはパスの誤入力 GitLab APIのプロジェクト指定時に、数字のプロジェクトID、またはURL形式の namespace/project-name を使用します。パスに特殊文字やスペースが含まれる場合は、URLエンコーディングが必須です。スラッシュ（/）は %2F にエンコードする必要があります。 Before（エラーが起きるコード）： # スラッシュがエンコードされていない curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/my-group/my-project/repository/commits" # 結果：404 Not Found After（修正後）： # スラッシュをURLエンコードする（%2F） curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/my-group%2Fmy-project/repository/commits" # または数字のプロジェクトIDを使用 curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/12345/repository/commits" 原因2：トークンの権限不足またはプロジェクトへのアクセス権限がない プライベートプロジェクトへのアクセスには、適切な権限を持つトークンが必要です。トークンが存在しない、有効期限が切れている、または該当プロジェクトへのアクセス権限がないメンバーが使用している場合、404が返されます。GitLabはセキュリティの観点から、権限がないリソースを404で返すため、403（Forbidden）と区別されません。 ...

エラーの概要 HTTP 409 Conflict エラーは、GitLab 上でリソースの状態が競合している場合に発生します。既に存在するブランチやタグ名での作成、MergeRequest のソースとターゲットブランチの重複、あるいは同名のグループ・プロジェクトの存在などが典型的な原因です。このエラーが発生すると、意図した操作がブロックされ、リソースの作成や更新が完了しません。 実際のエラーメッセージ例 GitLab API の 409 エラーは、以下のようなレスポンスで返されます。 { "message": "409 Conflict" } REST API でより詳細な情報が返される場合もあります。 { "message": { "base": ["Branch already exists"] } } また、GitLab UI でブランチ作成時に失敗する場合は、以下のような通知メッセージが表示されます。 Error: A branch with name 'main' already exists よくある原因と解決手順 原因 1：既に存在するブランチ名またはタグ名で作成しようとしている ブランチやタグの作成時に、既に同名のリソースが存在する場合、409 エラーが発生します。これは Git の基本的な制約で、同じ名前空間内で重複するブランチやタグを持つことはできません。API 経由でのブランチ作成や、CI/CD パイプライン内での自動ブランチ生成時に特に注意が必要です。 Before（エラーが起きるコード）： # 既に 'develop' ブランチが存在する場合、同じ名前で再度作成しようとする curl --request POST https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches \ --header "PRIVATE-TOKEN: <your-token>" \ --data "branch=develop&ref=main" After（修正後）： # 事前にブランチの存在を確認してから作成する RESPONSE=$(curl --request GET https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches/develop \ --header "PRIVATE-TOKEN: <your-token>" \ --write-out "\n%{http_code}") HTTP_CODE=$(echo "$RESPONSE" | tail -1) # ブランチが存在しない場合（404）のみ作成 if [ "$HTTP_CODE" = "404" ]; then curl --request POST https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches \ --header "PRIVATE-TOKEN: <your-token>" \ --data "branch=develop&ref=main" else echo "Branch already exists" fi 原因 2：MergeRequest のソースブランチとターゲットブランチが同じになっている MergeRequest を作成する際、ソースブランチとターゲットブランチが同じ場合に 409 エラーが発生します。これは論理的に無意味な操作（自分自身へのマージ）であるため、GitLab はこれを防止しています。複雑なパイプライン設定や自動化スクリプト内で、ブランチ変数の設定ミスにより起こることがあります。 ...

エラーの概要 GitLabの422エラーは「Unprocessable Entity」を意味し、リクエスト自体は正しく到達したものの、送信されたデータが検証ルールを満たしていないことを示します。プロジェクト作成、マージリクエスト、イシューなどのAPI操作で頻繁に発生し、GitLabサーバー側がデータの内容を受け入れられない状態です。 実際のエラーメッセージ例 GitLabのAPI経由で発生した422エラーの典型的なレスポンスは以下のようなJSON形式です。 { "message": "422 Unprocessable Entity", "error": "Validation failed", "errors": { "title": ["can't be blank"], "description": ["is invalid"] } } ブラウザのWebUIで遭遇した場合のエラー表示例： 422 Unprocessable Entity Failed to create merge request: Title can't be blank よくある原因と解決手順 原因1：マージリクエストのタイトルが空白になっている マージリクエスト作成時にtitleフィールドが空文字列または省略されると、GitLabの検証ルールに違反して422エラーが発生します。GitLab APIではtitleが必須フィールドとして定義されており、どのような値でも良いわけではなく「空でない文字列」という最小限の検証を通す必要があります。 修正前（エラーが起きるコード）： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects/<project-id>/merge_requests" \ --data "source_branch=feature-branch&target_branch=main&title=" 修正後： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects/<project-id>/merge_requests" \ --data "source_branch=feature-branch&target_branch=main&title=Add new feature" 原因2：プロジェクト名がグループのルールに違反している グループレベルで名前の長さ制限や命名規則が設定されている場合、その規則に適合しないプロジェクト名で作成しようとすると422エラーが返されます。特に大規模な組織では、プロジェクト命名を統一するためにグループ管理者が検証ルールを配置していることがあります。 修正前（エラーが起きるコード）： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects" \ --data "name=ThisProjectNameIsWayTooLongAndViolatesGroupNameLengthRestrictions&namespace_id=<group-id>" 修正後： ...