はじめに
さくらクラウドのオブジェクトストレージなどをTerraformの backend "s3" として利用していると、突如としてStateファイルが破損し、以下のエラーが発生することがあります。
発生するエラーメッセージ例：
Error: Failed to load state: Unsupported state file formatError: Decoding state file failed: invalid character '1' looking for beginning of valueThe state file does not have a "version" attribute.
これらのエラーが出た際、オブジェクトストレージ上の .tfstate を直接確認すると、ファイルの先頭に 19ce や 1a2b といった謎の16進数が書き込まれている場合があります。
本記事では、この「チャンク混入問題」の原因と、skip_s3_checksum を使った解決策を解説します。
原因：S3互換ストレージと「aws-chunked」の不整合
この現象は、Terraform（AWS SDK）がデータ転送時に使用する aws-chunked（チャンクアップロード） 形式のデータと、S3互換ストレージ側の処理の相性によって発生します。
本来は通信上の制御情報であるはずの「チャンク長（16進数）」が、ストレージ側で「データ本体の一部」として誤って保存されてしまうのが原因です。
- 主な発生環境: Terraform v1.5.0 系（SDKの挙動変更により顕著化）
- 対象ストレージ: さくらオブジェクトストレージ、および一部のS3互換ストレージ
対策手順：skip_s3_checksum の導入
この問題を根本的に回避するには、TerraformのBackend設定でチェックサム付与をスキップさせます。
1. Terraform 本体のアップデート
まずは、S3互換ストレージとの通信不具合が修正されている Terraform v1.6.6 以上 へのアップグレードを推奨します。
2. backend 設定の修正
backend "s3" ブロックに skip_s3_checksum = true を追加します。これが最も重要な対策です。
Terraform
terraform {
backend "s3" {
bucket = "your-bucket-name"
key = "path/to/terraform.tfstate"
region = "ap-northeast-1"
endpoint = "https://s3.isk01.sakurastorage.jp"
# --- S3互換ストレージ向けの必須設定 ---
force_path_style = true
skip_credentials_validation = true
skip_region_validation = true
skip_requesting_account_id = true
# --- 【重要】今回のエラー対策 ---
skip_s3_checksum = true
}
}
3. 設定の反映
Bash
terraform init -reconfigure
壊れてしまったStateの復旧方法
すでに先頭に 19ce 等が混入して Unsupported state file format となっている場合、Terraformコマンドからは修復できません。
- バージョニングから復元: さくら側のバケットでバージョニングが有効なら、正常だった世代にロールバックするのが最善です。
- 手動クリーンアップ: * 該当の
.tfstateをダウンロード。- テキストエディタ（バイナリエディタ等）で開き、先頭の
{より前にある16進数（例:19ce）を削除。 { "version": ...から始まる正しいJSON形式にして保存し、ストレージへ手動で上書きアップロードする。
- テキストエディタ（バイナリエディタ等）で開き、先頭の
- 再作成（最終手段）: どうしても復旧できない場合は、Stateを削除して
terraform importでリソースを紐付け直します。
まとめ
さくらオブジェクトストレージで Unsupported state file format が出たら、まずはStateの先頭にゴミが入っていないか確認しましょう。
対策は 「Terraform 1.6.6+ への更新」と「skip_s3_checksum = true の追加」 です。一度設定しておけば、以降の破損を防ぐことができます。
よくある質問（Q&A）：Terraform S3 Backend のトラブルシューティング
Q1. なぜ AWS S3 以外（さくら等）だとこのエラーが出るのですか？
A. Terraform の標準 S3 Backend は AWS 本家向けに最適化されており、最新の SDK ではデータ整合性を高めるために aws-chunked 形式やチェックサム（SHA256）を付与して送信します。さくらオブジェクトストレージなどの S3互換ストレージ の一部は、この特殊なチャンク形式の解析に完全対応していない場合があり、制御用の16進数（チャンク長）をデータ本体として保存してしまうため、JSON 形式が壊れてしまいます。
Q2. skip_s3_checksum = true を設定しても安全ですか？
A. はい、安全です。このオプションは、アップロード時に HTTP ヘッダーにチェックサムを付与する機能をオフにするものですが、通信自体は HTTPS で保護されており、ストレージ側での整合性チェックも従来通り行われるため、実用上のリスクは極めて低いです。むしろ、State が壊れるリスクを避けるために S3互換ストレージ利用時は必須の設定 と言えます。
Q3. Invalid character '1' looking for beginning of value と出ます。
A. まさにそれが本件の典型的なエラーメッセージです。State ファイルの 1行目、本来なら {（波括弧）で始まるべき場所に 19ce などの数字（文字 ‘1’ など）が混入していることを示しています。本記事の対策手順に従って Backend 設定を修正し、壊れた State を手動で修復してください。
Q4. さくら以外の S3互換（MinIO, Cloudflare R2, Wasabi等）でも発生しますか？
A. 発生する可能性があります。特に独自の API 実装を持つオブジェクトストレージで、Terraform v1.5.x 以降を使用した場合に報告されています。設定に endpoint や force_path_style = true を入れている環境であれば、あわせて skip_s3_checksum = true を入れておくのが定石です。
Q5. 複数人での開発で State Lock（排他制御）は効きますか？
A. さくらオブジェクトストレージ単体では、AWS の DynamoDB のような Lock 機能は提供されていません。そのため、複数人で同時に apply すると State が競合するリスクがあります。対策として、Terraform v1.10 以降で導入された use_lockfile = true を試すか、CI/CD（GitHub Actions 等）経由で実行を一本化し、同時実行を防ぐ運用を推奨します。
Q6. terraform init で HTTP 403 Forbidden や 405 Method Not Allowed が出る場合は？
A. skip_credentials_validation = true や skip_region_validation = true が抜けていないか確認してください。S3互換ストレージは AWS 固有の認証エンドポイントを持っていないため、これらを true にしないと初期化段階でエラーになることが多いです。
