CSVインポートで**「列数が不正です」「項目数が一致しません」**と出たら、まず疑うのはデータの中身よりCSVの構造だ。
3列のつもりでも、引用されていないカンマが1個入れば4列として読まれる。逆に末尾の空欄を表すカンマが消えれば、必要な列が1つ足りなくなる。
最初にやることは、元CSVを保存したまま、最初に列数がずれるレコードを特定すること。Excelで開いて保存し直す前に、CSVそのものを見る。
1. ヘッダーとデータ行の列数を比べる
たとえばヘッダーが3列なら、各データ行もCSVパーサー上で3列になっている必要がある。
name,address,age
Taro,Tokyo,20
これは3列。
一方、住所にカンマが入った次の行は、そのままだと4列として解釈される。
name,address,age
Taro,Tokyo, Japan,20
値の一部としてカンマを使うなら、フィールド全体を引用する。
name,address,age
Taro,"Tokyo, Japan",20
「見た目では3項目」ではなく、CSVパーサーが何フィールドとして読むかを見る。
2. 値の中のカンマを確認する
商品名、住所、備考などはカンマを含みやすい。
引用されていないカンマは区切り文字として扱われるため、特定の行だけ列数が増える原因になる。
手でカンマを消す前に、そのカンマが本来必要な文字なのかを確認する。必要な値を削るのではなく、正しく引用する。
3. ダブルクォートの閉じ忘れを見る
引用符が途中で閉じていないCSVは、後続のカンマや改行まで同じフィールドとして解釈されることがある。
id,note,status
1,"確認中,open
2,完了,closed
この場合、エラーが出た行だけを見ても原因が見つからないことがある。最初に壊れた行と、その直前の行をセットで確認する。
引用されたフィールド内でダブルクォート自体を表現するときは、一般的なCSVでは "" のように二重化する。
4. セル内改行を確認する
備考欄や住所欄には改行が入ることがある。
引用符で正しく囲まれた改行は1フィールドとして扱えるが、CSVを単純に「1行ずつ」「カンマでsplit」する処理では壊れる。
そのため、列数チェックもCSVの引用ルールを理解するパーサーで行う。単純な文字数やカンマ数だけでは判定しない。
5. 末尾の空欄を消していないか確認する
次の行は3列だ。
A,B,
最後のカンマは「3列目が空欄」を表している。
これを A,B にすると2列になる。CSV生成時の処理や手作業で末尾の区切り文字が落ちると、一部の行だけ列数不足になる。
6. 区切り文字が本当にカンマか確認する
拡張子が .csv でも、実体がタブ区切りやセミコロン区切りの場合がある。
インポート先がカンマ区切りを要求しているのに別の区切り文字を使っていれば、正常な列として認識されない。
「列数が不正です」を直す順番
- 元CSVをコピーして残す
- ヘッダーの列数を確認する
- 最初に列数が違うレコードを特定する
- その行と直前の行のカンマ・引用符・改行を見る
- 末尾空欄と区切り文字を確認する
- 修正後に全レコードをもう一度CSVパーサーで検査する
列数が直っても、必須値の空欄、重複、重複ヘッダーなどでインポートが止まることはある。構造エラーとデータ内容のエラーは分けて見る。
関連: CSVインポート前チェックリスト
壊れ方を試すための無料サンプルCSVも公開している。
毎回手で探したくない場合
CSV Preflight v0.1 は、必須値・重複・重複ヘッダー・列数不一致・引用符崩れをインポート前にローカルで点検する小さなツールだ。CSVを外部へ送信せず、買い切りUS$3で使える。
自動修復ではなく、壊れたCSVを本番へ入れる前に止めるための道具として使う。

