トラブルシューティング
はじめに
このガイドでは、Kovaを使う際によく発生する問題とその解決策をまとめています。エラーメッセージや症状から該当する項目を探してください。
問題が解決しない場合は、このページの末尾にある「それでも解決しない場合」を参照してください。
エラー別の解決策
WALLET_NOT_FOUND エラー
症状: kova balance や kova send を実行すると WALLET_NOT_FOUND エラーが表示される。
原因: デフォルトウォレットが設定されていないか、指定したウォレット名が存在しない。
解決策:
# ウォレット情報を確認する
kova wallet info
# デフォルトウォレットを設定する
kova config set defaultWallet <ウォレット名>
# ウォレットがない場合は初期セットアップを実行する
kova init残高が0と表示される
症状: kova balance を実行すると残高が0と表示され、送金操作ができない。
原因: アドレスの確認不足、チェーンの指定誤り、またはネットワーク接続の問題が考えられます。
解決策:
# ウォレットのアドレスを確認する
kova wallet info
# 全チェーンの残高を一覧表示する
kova balance表示されたアドレスに実際にトークンが存在するか、ブロックエクスプローラー（例: Basescan）で確認してください。
送金トランザクションが失敗する
症状: kova send を実行すると TX_FAILED エラーが表示される。
原因: ガス代不足、RPC接続の問題、または送金額が残高を超えている可能性があります。
解決策:
# まずdry-runで内容を確認する（--broadcastを付けない）
kova send --name my-wallet --to 0xRecipientAddress --amount 0.01 --chain base
# 残高とガス代を確認してから送信する
kova balance
kova send --name my-wallet --to 0xRecipientAddress --amount 0.01 --chain base --broadcastガス代はETHで支払われます。送金額とは別に少量のETHを残高として保持してください。
RPC接続エラー
症状: コマンド実行時にネットワークエラーやタイムアウトが発生する。
原因: デフォルトのRPCエンドポイントが混雑しているか、ネットワーク環境の問題が考えられます。
解決策:
# カスタムRPCエンドポイントを設定する
kova config set rpc.base https://your-rpc-endpoint.com
kova config set rpc.ethereum https://your-ethereum-rpc.com
# 設定を確認する
kova config showInfura、Alchemy、QuickNodeなどのRPCプロバイダーから無料プランで専用エンドポイントを取得できます。
CHAIN_NOT_SUPPORTED エラー
症状: send / swap などのコマンドで --chain を指定すると CHAIN_NOT_SUPPORTED エラーが表示される。
原因: チェーン名の指定が正しくない。
解決策:
正しいチェーン名を使用してください。
# 正しいチェーン名の例（send コマンドでの使用）
kova send --name my-wallet --to 0x... --amount 0.01 --chain base
kova send --name my-wallet --to 0x... --amount 0.01 --chain base-sepolia
kova send --name my-wallet --to 0x... --amount 0.01 --chain ethereum
# 誤った例（使用できない）
# kova send ... --chain Base
# kova send ... --chain ETH
# kova send ... --chain mainnetなお kova balance は --chain を受け付けません。引数なしで全サポートチェーンの残高を一覧表示します。
サポートされているチェーンの一覧は対応チェーン一覧を参照してください。
スキルが起動しない（AIエージェント連携）
症状: AIエージェントからスキルを呼び出しても認識されない、またはエラーになる。
原因: スキルが正しくインストールされていないか、パスの設定に問題があります。
解決策:
# インストール済みスキルを確認する
kova skills list
# スキルのパスを確認する
which kova
echo $PATH
# スキルを再インストールする
kova skills installAIエージェントフレームワークの設定でスキルのパスが正しく指定されているか確認してください。
kova の実行が遅い
症状: コマンドを実行するたびにダウンロードが発生し、起動に時間がかかる。
原因: npxは都度パッケージをダウンロードするため、毎回時間がかかります。
解決策:
# グローバルインストールに切り替える
npm install -g @komlock_lab/kova
# インストール後はkovaコマンドで即座に実行できる
kova --versionAPI鍵が機能しない
症状: POLICY_DENIED または認証エラーが発生する。
原因: API鍵が無効、期限切れ、または環境変数が正しく設定されていない可能性があります。
解決策:
# 登録済みAPI鍵を確認する
kova key list
# 環境変数での設定を確認する
echo $KOVA_API_KEY
# 環境変数でAPI鍵を設定する（bashの場合）
export KOVA_API_KEY=your-api-key
# 設定ファイルでAPI鍵を設定する
kova config set apiKey your-api-keyAPI鍵が正しい場合でも権限が不足していると POLICY_DENIED になることがあります。鍵に付与されている権限を確認してください。
それでも解決しない場合
エラーコードを調べる:
エラーコードが表示された場合はエラーコードリファレンスで詳細な説明と対処法を確認してください。