Python ValueError: invalid literal for int() の原因と解決方法【よくある落とし穴と実践的な対処法】

ValueError: invalid literal for int() with base 10: ‘…’ とは

Pythonで文字列を数値に変換しようとした際に遭遇するValueError: invalid literal for int() with base 10エラーは、特にユーザー入力やファイル読み込み、APIからのデータ処理で頻繁に発生します。このエラーは、数値として解釈できない文字列をint()関数に渡したときに発生し、プログラムの予期せぬ終了を引き起こすことがあります。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: パターン1: ユーザー入力が数値ではない

# ユーザーからの入力を受け取る
user_input = input("数字を入力してください: ") # 例: 'abc' と入力

# 文字列を整数に変換しようとする
num = int(user_input)
print(f"入力された数字: {num}")

input()関数は常に文字列を返します。ユーザーが数字以外の文字列（例: ‘abc’）や空文字を入力した場合、int()関数はその文字列を10進数の数値として解釈できないため、ValueErrorが発生します。

# ユーザーからの入力を受け取る
user_input = input("数字を入力してください: ")

# 数値変換前にバリデーションまたはエラーハンドリングを行う
try:
    num = int(user_input)
    print(f"入力された数字: {num}")
except ValueError:
    print(f"エラー: '{user_input}' は有効な数字ではありません。")

# または、事前チェック
if user_input.isdigit(): # 正の整数のみをチェックする場合
    num = int(user_input)
    print(f"入力された数字: {num}")
else:
    print(f"エラー: '{user_input}' は有効な数字ではありません。")

パターン2: パターン2: ファイルから読み込んだデータに非数値が含まれる

# scores.txt の内容: 
# 100
# 95
# N/A
# 80

with open('scores.txt', 'r') as f:
    for line in f:
        # 各行を数値に変換しようとする
        score = int(line.strip())
        print(f"スコア: {score}")

ファイルから読み込んだデータは通常文字列として扱われます。特にCSVやログファイルなどでは、欠損値やエラーを示す文字列（例: ‘N/A’, ‘-‘）が数値の列に混入していることがあります。strip()で空白を除去しても、非数値文字列はint()で変換できません。

# scores.txt の内容: 
# 100
# 95
# N/A
# 80

with open('scores.txt', 'r') as f:
    for line in f:
        clean_line = line.strip()
        # 数値変換前にエラーハンドリングまたは条件分岐で対応
        try:
            score = int(clean_line)
            print(f"スコア: {score}")
        except ValueError:
            print(f"警告: '{clean_line}' は無効なスコアです。スキップします。")
            # またはデフォルト値を設定する: score = 0

パターン3: パターン3: APIレスポンスのデータ型不一致

import json

# APIからのレスポンスを想定 (status_codeが文字列)
api_response_str = '{"id": 101, "item_name": "Widget", "status_code": "200"}'
# または、status_codeが予期せず空文字やnullだった場合
# api_response_str = '{"id": 101, "item_name": "Widget", "status_code": ""}'

response_data = json.loads(api_response_str)

# status_codeを整数として使用したい
status_code_int = int(response_data['status_code'])
print(f"ステータスコード: {status_code_int}")

外部APIからのJSONレスポンスは、ドキュメントと異なるデータ型で値が返されることがあります。特に、数値と期待していたフィールドが文字列（例: ‘200’）として返されたり、空文字やnullで返されたりすると、そのままint()に渡すとValueErrorが発生します。

import json

api_response_str = '{"id": 101, "item_name": "Widget", "status_code": "200"}'
# api_response_str = '{"id": 101, "item_name": "Widget", "status_code": ""}'
# api_response_str = '{"id": 101, "item_name": "Widget", "status_code": null}'

response_data = json.loads(api_response_str)

status_code_raw = response_data.get('status_code')

try:
    # nullや空文字の場合はNoneになるため、int()に渡す前にチェック
    if status_code_raw is None or str(status_code_raw).strip() == '':
        status_code_int = 0 # デフォルト値など
        print(f"警告: ステータスコードが不正なため、デフォルト値 {status_code_int} を使用しました。")
    else:
        status_code_int = int(status_code_raw)
        print(f"ステータスコード: {status_code_int}")
except ValueError:
    print(f"エラー: '{status_code_raw}' は無効なステータスコードです。")
    status_code_int = -1 # エラー時の値など

根本原因の特定方法

エラーが発生したら、まず{marker}int()関数に渡されている変数の値と型をprint()関数やデバッガで確認{/marker}しましょう。print(f"Value: {variable}, Type: {type(variable)}")のように出力することで、問題の原因（変数が期待する型や値ではないこと）を特定しやすくなります。

# エラーが発生しそうな場所の直前で変数をチェック
user_input = "abc"
# user_input = "123"

print(f"デバッグ情報: user_input = '{user_input}', type = {type(user_input)}")

try:
    num = int(user_input)
    print(f"変換された数字: {num}")
except ValueError as e:
    print(f"エラーを捕捉しました: {e}")

防止策とベストプラクティス

数値変換前には、{marker}入力値が数値として有効であるかを事前にチェック{/marker}するか、try-exceptブロックでエラーを捕捉してプログラムが停止しないようにすることが最も効果的な予防策です。文字列のメソッド（isdigit()など）や正規表現を使って数値形式を検証することも有効です。

# 予防策1: isdigit() で事前チェック
user_input = input("数字を入力してください: ")
if user_input.isdigit(): # 正の整数のみを判定
    num = int(user_input)
    print(f"入力された数字: {num}")
else:
    print(f"エラー: '{user_input}' は有効な数字ではありません。")

# 予防策2: try-except ブロックでエラーハンドリング
def safe_int_conversion(value):
    try:
        return int(value)
    except ValueError:
        return None # 変換失敗時はNoneを返すなど

input_value = "not_a_number"
converted_num = safe_int_conversion(input_value)
if converted_num is not None:
    print(f"変換成功: {converted_num}")
else:
    print(f"変換失敗: '{input_value}' は数値ではありませんでした。")

よくある質問（FAQ）

この用語と一緒に知っておきたい用語