Skip to content

エラーメッセージの読み方

このガイドでは、kazunokoを使用中に出現するエラーメッセージの意味と対応方法を説明します。

エラーメッセージの基本構造

ターミナルに出力されるメッセージには、以下の情報が含まれています。

[red]Error: デバイスが接続されていません[/red]
要素 意味
[red] 赤色で表示（エラー）
Error: エラータイプの識別子
メッセージ本文 何が起きたかの説明

メッセージ色の意味

メッセージの重要度を色で表しています。

色 意味 例
[cyan] INFO（情報） 「接続しました」「読み込み中...」
[green] SUCCESS（成功） 「完了しました」「保存されました」
[yellow] WARNING（警告） 問題があり処理をスキップした場合
[red] ERROR（赤） 重大な問題で処理を中止した場合

よくあるエラーと対応

1. 接続エラー

No serial ports found

接続先のシリアルポートが見つからない場合に表示されます。

Error: No suitable serial port found for OSECHI detector.

Available ports:
  (None found)

原因:

  • USBケーブルが接続されていない
  • デバイスが正常に認識されていない
  • ドライバーがインストールされていない

対応方法:

# 1. 物理的な接続を確認
# → デバイスのUSBケーブルをしっかり差し込む

# 2. 接続されているポートを確認
uv run kazunoko status

# 3. 別のUSBポートを試す
uv run kazunoko status --port /dev/ttyUSB0
uv run kazunoko status --port /dev/ttyUSB1

# 4. モックモードで試す（デバイスなしで動作確認）
uv run kazunoko read 5 --mock

Failed to open serial port

シリアルポートが正常に開けない場合に表示されます。

Error: Failed to open serial port /dev/ttyUSB0: Permission denied

原因:

  • ユーザーがシリアルポートにアクセスする権限がない
  • デバイスが他のプロセスで使用されている

対応方法（Linux/macOS）:

# 1. デバイスの権限を確認
ls -la /dev/ttyUSB*

# 2. ユーザーをグループに追加（Linux）
sudo usermod -a -G dialout $USER

# 3. macOSの場合
sudo chown $USER /dev/ttyUSB*

# 4. ログアウト/ログインして反映させる

2. タイムアウトエラー

No response received within X s timeout

シリアルポートの接続がタイムアウトした場合に表示されます。

Error: No response received within 0.1s timeout

原因:

  • デバイスの電源が入っていない、または応答していない
  • USB接続が不安定
  • シリアル通信がハングアップしている

対応方法:

# 1. デバイスの電源を確認
# → LEDが点灯しているか確認

# 2. デバイスの状態を確認
uv run kazunoko status --verbose

# 3. 通信タイムアウト値を増やす
uv run kazunoko status --timeout 1.0
uv run kazunoko read 100 --timeout 1.0

# 4. デバイスを再起動する
# → デバイスの電源を切って、10秒待つ
# → 再度電源を入れる

# 5. ケーブルを接続し直す
# → USBケーブルを抜いて、別のポートに接続

# 6. ログを確認して詳細を見る
cat ~/Library/Logs/kazunoko/kazunoko.json

3. イベント読み出しエラー

No event received within X s timeout

指定された時間内にイベント（検出データ）が受け取れなかった場合に表示されます。

⏱ Event 23/1000: No event received within 5.0s timeout

原因:

  • スレッショルド値が高すぎて、イベント検出が少ない
  • デバイスが正常に動作していない
  • 測定環境にミューオンが少ない

対応方法:

# 1. スレッショルドを下げる
#    （より多くのイベントを検出）
uv run kazunoko measure "1:250;2:300;3:280" 100

# 2. poll_countを増やす
#    （各試行でデバイスを詳細に検索）
uv run kazunoko read 100 --poll-count 65535

# 3. イベントタイムアウトを長くする
uv run kazunoko read 100 --event-timeout 30.0

# 4. デバイスのステータスを確認
uv run kazunoko status --verbose

補足: スレッショルド値の説明

スレッショルド = イベントを検出する「感度」

値が小さい   → より敏感に反応   → イベント数が多い（✓）
値が大きい   → 反応しにくい     → イベント数が少ない（✗）

Malformed event data

デバイスから受け取ったデータが、期待される形式ではない場合に表示されます。

⚠ Malformed event data, skipping: Invalid JSON: Expecting value

原因:

  • デバイスのファームウェアが古い
  • USB接続が不安定でデータが破損
  • デバイスが異常な状態

対応方法:

# 1. デバイスのバージョンを確認
uv run kazunoko version

# 2. デバイスをリセット
uv run kazunoko reset

# 3. ケーブルを接続し直す
# → USBケーブルを抜いて、別のポートに接続

# 4. 別のUSBケーブルを試す

# 5. 詳細ログを確認
cat ~/Library/Logs/kazunoko/kazunoko.json | tail -20

# 6. デバッグレベルで実行
uv run kazunoko --level debug read 5 2> debug.log

4. ファイル出力エラー

No such file or directory

出力先が存在しない場合に表示されます。

Error: [Errno 2] No such file or directory: '20241216/events.jsonl'

原因:

  • 出力先のディレクトリが存在しない
  • パスが間違っている

対応方法:

# 1. 現在の位置を確認
pwd

# 2. ディレクトリを作成
mkdir -p 20241216

# 3. 再度実行
uv run kazunoko read 100 > 20241216/events.jsonl

# または、スクリプトが自動生成する場合
uv run examples/get_events.py "1:300;2:320;3:310" 100 --save

Permission denied

出力先に書き込み権限がない場合に表示されます。

Error: Permission denied: '/root/events.jsonl'

原因:

  • 書き込み権限がない
  • ディレクトリが読み取り専用

対応方法:

# 1. 別の場所に保存（ホームディレクトリ推奨）
uv run kazunoko read 100 > ~/events.jsonl

# 2. ディレクトリの権限を確認
ls -la ~/

# 3. 権限を変更（必要な場合）
chmod 755 /path/to/directory
chmod 644 /path/to/file

エラーメッセージから情報を抽出する

エラーが出たときは、以下の情報をメモしてください。

  • 完全なエラーメッセージ（コピー&ペースト）
  • 実行したコマンド
  • デバイスの状態（接続されている？）
  • OSとバージョン
  • Pythonバージョン（python --version）
  • kazunokoのバージョン（uv run kazunoko version）

ログファイルでエラーの詳細を確認

エラーメッセージだけでは不十分な場合、ログファイルで詳細を確認できます。

# ログファイルの最後の20行を表示
tail -20 ~/Library/Logs/kazunoko/kazunoko.json

# JSON形式なので、jqで見やすく表示（jqがインストール済みの場合）
cat ~/Library/Logs/kazunoko/kazunoko.json | jq '.message'

# または、テキストエディタで直接開く
open ~/Library/Logs/kazunoko/kazunoko.json

ログの詳しい読み方は、ログの基礎を参照してください。

エラーが解決しない場合

以下の手順を試してください。

  1. デバイスを再起動
# デバイスの電源を切る → 10秒待つ → 再度電源を入れる
  1. モックモードで動作確認
# デバイスなしで正常に動作するか確認
uv run kazunoko read 5 --mock
  1. キャッシュをクリア
# 古い接続情報をクリア
rm -rf ~/.cache/kazunoko
  1. ログを記録して報告
# デバッグログを有効化して実行
uv run kazunoko --level debug read 5 2> error_report.log

# ログファイルをGitLabでissueに添付して報告

詳しくは デバッグモード を参照してください。

次のステップ

  • エラーの原因を特定したら、該当するセクションで詳細な対応方法を確認してください
  • 引き続き問題がある場合は、ログの基礎でログの読み方を学んでください
  • パラメータを調整して改善する方法は、パラメータ調整を参照してください