error-message-explainer

エラーメッセージ解説

Arduino／ESP32／RP2040 プロジェクトの分かりにくいコンパイラーエラーを、具体的な修正方法に変換します。

リソース

このスキルには、以下のツールが含まれています。

• scripts/parse_errors.py - 20 種類以上のエラーパターンを使った自動エラー分析
• ../../docs/board-support/uno-r4-family.md - Uno R4 ボードファミリー共通の注意事項

クイックスタート

ファイルからエラーを分析：

uv run --no-project scripts/parse_errors.py --file error_log.txt

単一のエラーを分析：

uv run --no-project scripts/parse_errors.py --message "error: 'LED' was not declared in this scope"

対話モード：

uv run --no-project scripts/parse_errors.py --interactive

コンパイラーからパイプで入力：

arduino-cli compile 2>&1 | uv run --no-project scripts/parse_errors.py --stdin

このスキルの使い方

ユーザーがエラーメッセージを貼り付けた場合：

1. 以下のパターンからエラーの種類を特定します
2. 何を意味するか、分かりやすく説明します
3. コード例を使って具体的な修正方法を示します
4. このエラーが発生する理由を説明します（学習に役立ちます）
5. ターゲットが Uno R4 ファミリーで、WiFi、OTA、USB、またはボード認識に関する問題の場合は、../../docs/board-support/uno-r4-family.md を開きます

復旧の境界

リセット、消去、ブートローダーの修復、または再書き込みを勧める前に、ボードとリビジョン、ツールとライブラリのバージョン、ポート、電源経路、最後に正常動作したイメージを正確に記録してください。アップロードの失敗、起動の失敗、電源の問題、またはファームウェアの破損については、ルーターの復旧リファレンスを使用してください。コンパイルの修正を、ハードウェアやシステムの修正として扱わないでください。

よくあるコンパイルエラー

1. "'xyz' was not declared in this scope"

error: 'xyz' was not declared in this scope

意味： コンパイラーが名前 xyz を認識していません。

よくある原因と修正方法：

原因	修正方法
変数名または関数名のタイプミス	スペルを確認します。C++ では大文字と小文字が区別されます！
宣言より前に変数を使用している	最初に使用する箇所より前に宣言を移動します
#include が不足している	必要なライブラリのヘッダーを追加します
関数を呼び出しより後に定義している	前方宣言を追加するか、関数を前に移動します

例 - タイプミス：

// WRONG
int ledpin = 13;      // lowercase 'p'
digitalWrite(ledPin, HIGH);  // uppercase 'P' - DIFFERENT!

// CORRECT
int ledPin = 13;
digitalWrite(ledPin, HIGH);

例 - Include の不足：

// WRONG - Servo not defined!
Servo myServo;

// CORRECT
#include <Servo.h>
Servo myServo;

---

2. "expected ';' before..."

error: expected ';' before 'xyz'

意味： 前の行にセミコロンがありません。

修正方法： エラーのある行の直前の行末に ; を追加します。

// WRONG - error points to line 3
int x = 5       // ← missing ; here!
int y = 10;

// CORRECT
int x = 5;
int y = 10;

ヒント： エラー行番号は、コンパイラーが問題に気付いた位置であり、; が抜けている位置とは限りません！

---

3. "expected ')' before..." または "expected '}' before..."

error: expected ')' before ';'
error: expected '}' at end of input

意味： 括弧または波括弧が対応していません。

よくあるパターン：

// WRONG - unmatched parenthesis
if (x > 5 {  // missing )
}

// WRONG - unmatched brace
void setup() {
    Serial.begin(115200);
// missing closing }

// CORRECT
if (x > 5) {
}

void setup() {
    Serial.begin(115200);
}

デバッグのヒント： IDE の自動整形（Ctrl+T）を使うと、対応していない箇所を見つけやすくなります。

---

4. "invalid conversion from 'const char*' to 'char*'"

error: invalid conversion from 'const char*' to 'char*'

意味： 文字列リテラル（読み取り専用）を変更しようとしています。

// WRONG
char* message = "Hello";  // string literals are const!
message[0] = 'h';         // can't modify!

// CORRECT (if you need to modify)
char message[] = "Hello"; // creates modifiable copy
message[0] = 'h';         // OK!

// CORRECT (if read-only is fine)
const char* message = "Hello";

---

5. "no matching function for call to..."

error: no matching function for call to 'SomeClass::method(int, int, int)'
note: candidate: void SomeClass::method(int, int)

意味： 関数に、数または型が正しくない引数を渡しています。

// WRONG - too many arguments
myServo.write(90, 100);  // write() takes only 1 argument!

// CORRECT
myServo.write(90);

「note:」の行を確認してください。受け付けられる引数が示されています。

---

6. "multiple definition of 'xyz'"

error: multiple definition of 'xyz'

意味： 同じ変数または関数が複数のファイルで定義されています。

修正方法：

// In header file (.h), use 'extern':
extern int globalVar;  // declaration only

// In ONE .cpp file, define it:
int globalVar = 0;     // actual definition

ヘッダー内の関数の場合：

// WRONG - defined in header, included multiple times
int add(int a, int b) { return a + b; }

// CORRECT - use 'inline'
inline int add(int a, int b) { return a + b; }

---

7. "'xyz' does not name a type"

error: 'WiFiClient' does not name a type

意味： クラスまたは型が認識されていません。

修正方法：

ボード	ライブラリ	Include
ESP32	WiFi	#include <WiFi.h>
ESP8266	WiFi	#include <ESP8266WiFi.h>
Arduino + WiFi Shield	WiFi	#include <WiFi.h>

// WRONG
WiFiClient client;  // WiFiClient unknown!

// CORRECT for ESP32
#include <WiFi.h>
WiFiClient client;

---

8. "redefinition of 'xyz'"

error: redefinition of 'int x'

意味： 同じスコープ内で変数を 2 回宣言しています。

// WRONG
int count = 0;
int count = 0;  // redefinition!

// WRONG in loops
for (int i = 0; i < 10; i++) {
    int i = 5;  // shadows loop variable!
}

// CORRECT
int count = 0;  // declare once
count = 5;      // assign without 'int'

---

アップロードエラー

9. "avrdude: stk500_recv(): programmer is not responding"

avrdude: stk500_recv(): programmer is not responding
avrdude: stk500_getsync() attempt X of 10: not in sync

意味： Arduino IDE がボードと通信できません。

修正方法（上から順に試してください）：

1. ✅ 正しいボードが選択されていますか？（Tools → Board）
2. ✅ 正しいポートが選択されていますか？（Tools → Port）
3. ✅ USB ケーブルはデータ転送に対応していますか（充電専用ではありませんか）？
4. ✅ 別の USB ポートを試します
5. ✅ ピン 0／1（TX／RX）に何も接続されていませんか？
6. ✅ アップロード中にリセットボタンを押します
7. ✅ USB ドライバーをインストールまたは再インストールします

---

10. "A fatal error occurred: Failed to connect to ESP32"

A fatal error occurred: Failed to connect to ESP32: 
Timed out waiting for packet header

意味： ESP32 がブートローダーモードに入っていません。

対処方法： アップロード中に BOOT ボタンを押し続けます。

1. IDE で「Upload」をクリックします
2. 「Connecting...」と表示されたら、BOOT ボタンを押し続けます
3. アップロードが始まったらボタンを離します
4. ボードによっては、BOOT を押し続けながら EN/RST を押し、BOOT を離します

---

11. "Sketch too big"

Sketch too big; see https://support.arduino.cc/...
Sketch uses 34816 bytes (107%) of program storage space.
Maximum is 32256 bytes.

意味： プログラムがフラッシュメモリに収まりません。

対処方法：

// 1. Use F() macro for strings (saves RAM + sometimes Flash)
Serial.println(F("This string in flash"));  // instead of RAM

// 2. Remove unused libraries
// Each #include adds code even if not used

// 3. Use smaller data types
uint8_t x = 5;  // instead of int (2 bytes saved)

// 4. Choose board with more flash (ESP32 has 4MB vs Arduino's 32KB)

---

ライブラリエラー

12. "fatal error: xyz.h: No such file or directory"

fatal error: Adafruit_BME280.h: No such file or directory

意味： ライブラリがインストールされていません。

対処方法：

1. 「Sketch」→「Include Library」→「Manage Libraries」を選択します
2. ライブラリ名を検索します
3. 「Install」をクリックします
4. ライブラリマネージャーにない場合：ZIP をダウンロードし、「Sketch」→「Include Library」→「Add .ZIP Library」を選択します

---

13. "exit status 1 / Error compiling for board..."

exit status 1
Error compiling for board Arduino Uno.

意味： 一般的なエラーです。上にスクロールして、実際のエラーメッセージを探してください。

実際のエラーはこの行より上にあります！ error: を含む行を探してください。

---

型エラー

14. "cannot convert 'String' to 'const char*'"

error: cannot convert 'String' to 'const char*'

意味： 関数は C 文字列を想定していますが、Arduino String が渡されています。

// WRONG
String myString = "hello";
someFunction(myString);  // if someFunction expects const char*

// CORRECT
String myString = "hello";
someFunction(myString.c_str());  // convert to C-string

---

15. "invalid operands to binary expression"

error: invalid operands of types 'const char*' and 'const char*' to binary 'operator+'

意味： C 文字列に + は使用できません。

// WRONG
const char* a = "hello";
const char* b = " world";
const char* c = a + b;  // doesn't work!

// CORRECT - use String
String a = "hello";
String b = " world";
String c = a + b;  // works!

// Or use snprintf
char c[20];
snprintf(c, sizeof(c), "%s%s", a, b);

---

クイックリファレンステーブル

エラーに含まれる文字列	考えられる問題	簡単な対処方法
"not declared"	タイプミスまたはインクルード漏れ	スペルを確認し、#include を追加します
"expected ';'"	セミコロンがありません	エラー行の上の行に ; を追加します
"expected ')'"	括弧が対応していません	( と ) の数を確認します
"expected '}'"	波括弧が対応していません	{ と } の数を確認します
"no matching function"	引数が正しくありません	関数のシグネチャを確認します
"does not name a type"	ライブラリがありません	#include を追加します
"multiple definition"	複数のファイルで定義されています	extern を使用します
"stk500"	アップロードに失敗しました	ボード、ポート、ケーブルを確認します
"No such file"	ライブラリがインストールされていません	ライブラリマネージャーからインストールします
"too big"	フラッシュメモリの容量不足です	F() を使用し、未使用のコードを削除します

デバッグの進め方

1. 最初のエラーを読みます（後続のエラーは連鎖していることがよくあります）
2. ファイル名と行番号を確認します
3. 該当する行と、その1行上を確認します
4. 上記の一般的なパターンを確認します
5. 一度に1つのエラーを修正し、再コンパイルします
6. エラーがなくなるまで繰り返します

共有出力の契約

共有 Arduino スキルの契約を使用してください。 前提条件、必要なツールとバージョン、実装手順、 検証段階ごとのテストと証拠、既知の制限事項、復旧とセキュリティに関する注意事項を明記します。