walrus-troubleshooting

Walrus のトラブルシューティング

ソースに関する制約： このスキルに記載されているすべてのエラーは、 Walrus のドキュメント、Walrus リポジトリ、または TypeScript SDK のソースに記載されています。 内容を追加する際は、追加するエラーの出典となるページまたはソースファイルを必ず記載してください。

このスキルでは、Walrus の使用時によく発生するエラーをツール別にまとめています。各項目には、エラーメッセージ、原因、対処方法を記載しています。

---

関連スキル

トピック	スキル	読み込むタイミング
CLI	walrus-cli	CLI の使い方と設定について確認するとき
TypeScript SDK	walrus-ts-sdk	SDK の初期化と使用方法について確認するとき
HTTP API	walrus-http-api	REST エンドポイントの使用方法について確認するとき
Move の統合	walrus-move-integration	Move の依存関係やコントラクトの問題が発生したとき
ストレージコスト	walrus-storage-costs	コストに関する質問があるとき
概要	walrus-overview	用語（blob ID と object ID など）について確認するとき

---

スキルの内容

CLI のエラー

spawn walrus ENOENT または command not found: walrus

原因： walrus バイナリがインストールされていないか、PATH に含まれていません。

対処方法：

curl -sSfL https://raw.githubusercontent.com/Mystenlabs/suiup/main/install.sh | sh
suiup install walrus

すでにインストール済みの場合は、~/.suiup/bin を PATH に追加してください。インストール後にシェルを再起動してください。

---

Cannot find gas coin for signer address

原因： ウォレットに SUI トークンがありません。Walrus の操作には、ガス代として SUI が必要です。

対処方法：

• Testnet： sui client faucet を実行して、テスト用の SUI を入手してください。
• Mainnet： 取引所で SUI を入手し、ウォレットアドレスに送金してください。

残高は sui client gas で確認できます。

---

could not find a valid Walrus configuration file

原因： CLI が client_config.yaml を見つけられません。

対処方法：

curl --create-dirs https://docs.wal.app/setup/client_config.yaml \
  -o ~/.config/walrus/client_config.yaml

または、パスを明示的に指定してください：walrus --config /path/to/client_config.yaml store ...

---

blobs can only be stored for up to MAX_EPOCHS epochs ahead

原因： 指定したストレージ期間が上限を超えています。現在の上限は 53 エポックです。walrus info で確認できます。

対処方法： --epochs 53 または --epochs max を指定し、有効期限が切れる前に延長するよう計画してください。

---

exactly one of epochs, earliest-expiry-time, or end-epoch must be specified

原因： walrus store に、有効期間を指定する 3 つのオプションのいずれも指定されていないか、複数指定されています。

対処方法： 次のいずれか 1 つだけを指定してください：--epochs <N|max>、--earliest-expiry-time <TIME>、または --end-epoch <N>。

---

deletable blobs cannot be shared

原因： walrus share に削除可能な blob が指定されました。共有する blob は永続的である必要があります。

対処方法： --permanent（または --permanent --share）を指定して保存し、その blob を共有してください。

---

The object ID of an exchange object must be specified ... this command is only available on Testnet

原因： Mainnet のコンテキストで walrus get-wal が実行されました。Mainnet では交換オブジェクトが定義されていません。

対処方法： get-wal は Testnet でのみ使用できます（walrus get-wal --context testnet）。Mainnet では、取引所で WAL を入手するか、WAL を保有するアドレスから送金してください。

---

設定を変更していないのにアップロードが断続的に失敗する

原因： クライアント側の問題ではなく、ストレージノードに到達できません。書き込みには n - f 個のシャード（1,000 個中 667 個）が必要です。正常なノード数がこの値をわずかに上回る状態では、書き込みに必要なノードが到達不能なノードの集合に入るたびに、個々の試行が失敗します。

対処方法：

walrus health --committee --sort-by status   # which nodes are in Error
walrus info bft                              # the write threshold n - f

正常なシャード数が n - f を大きく上回る場合は、通常どおりアップロードできます。わずかに上回る場合は、断続的な失敗が予想されるため、再試行してください。下回る場合は書き込みを承認できません。再試行するのではなく、ネットワークの復旧を待ってください。読み取りは n - 2f まで機能します。

---

Testnet の blob がすぐに消える

原因： Testnet のエポックは Mainnet のエポックより短いです。エポック数を小さくして保存すると、予想より早く blob の有効期限が切れます。

対処方法： walrus info で現在のエポック期間を確認してください。Testnet では余裕を持ったエポック数（30 以上）を指定してください。Mainnet では、1 エポックは 14 日です。

---

TypeScript SDK のエラー

ChainNotSupportedError: The account does not support the chain "sui:undefined"

原因： dApp Kit のウォレットアダプターに正しいネットワークが設定されていません。SDK が使用する Sui チェーンを特定できません。

対処方法： dApp Kit プロバイダーでチェーンを指定してください。

<SuiClientProvider networks={{ testnet: { url: getFullnodeUrl('testnet') } }} defaultNetwork="testnet">

また、ウォレットが同じネットワークに接続されていることを確認してください。

---

file.bytes is not a function

原因： バイナリデータではなく、生の文字列や JavaScript オブジェクトを blob として渡しています。

対処方法： 先に Uint8Array に変換してください。

// WRONG
await client.walrus.writeBlob({ blob: myJsonString, epochs: 5, deletable: true, signer });

// CORRECT
await client.walrus.writeBlob({
  blob: new TextEncoder().encode(myJsonString),
  epochs: 5,
  deletable: true,
  signer,
});

// Or use the WalrusFile API, which accepts a Uint8Array, Blob, or string
const file = WalrusFile.from({ contents: myJsonString, identifier: 'data.json' });
await client.walrus.writeFiles({ files: [file], epochs: 5, deletable: true, signer });

writeBlob が受け取るのは Uint8Array です。@mysten/walrus に storeBlob メソッドはありません。

---

Tip amount (N) exceeds the maximum allowed tip (M)

原因： アップロードリレーが、設定した最大値を超えるチップを要求しています。デフォルトの sendTip.max は、使用しているリレーに対して低すぎます。

対処方法： アップロードリレーの設定で sendTip.max の値を増やしてください。

uploadRelay: {
  host: 'https://upload-relay.mainnet.walrus.space',
  sendTip: { max: 5_000_000 },  // increase as needed
},

リレーが要求するチップを確認してください：curl <relay-url>/v1/tip-config

---

RetryableWalrusClientError: Too many failures while writing blob

原因： SDK が十分な数のストレージノードにスリバーを配布できませんでした。一般的な原因：

• ブラウザー環境でアップロードリレーが設定されていない
• ストレージノードへのネットワーク接続の問題
• ストレージノードが一時的に利用できない

対処方法：

1. ブラウザーでは、アップロードリレーを設定してください（walrus-ts-sdk のスキルを参照）。
2. ネットワーク接続を確認してください。
3. 指数バックオフで再試行してください。
4. 問題が続く場合は、別のアップロードリレーを試すか、ストレージノードの復旧を待ってください。
5. エポックの切り替わり前後では、クライアントにキャッシュされた委員会情報が古くなることがあります：if (error instanceof RetryableWalrusClientError) { client.walrus.reset(); /* retry */ }。storageNodeClientOptions: { onError } を渡すと、SDK が吸収する個々のノードエラーを確認できます。

---

BlobNotCertifiedError

原因： blob はオンチェーンに登録されていますが、ストレージノードから十分な数の確認をまだ受け取っていません。可用性証明書はまだ送信されていません。

対処方法： blob はまだ Point of Availability（PoA）に達していません。認証が完了するまで待ってください。完了しない場合は、アップロードが途中で失敗した可能性があります。保存処理を再試行してください。

---

Vite、Next.js、または別のバンドラーが SDK の WASM モジュールを読み込めない

原因： SDK は blob のエンコードとデコードに WASM バインディングを必要としますが、バンドラーが実行時にバイナリを見つけられません（Turbopack では、/ROOT/... のような仮想化されたパスとして表示されます）。

対処方法： WASM の場所をクライアントに指定してください。

// Vite: import the file with ?url and pass it as wasmUrl
import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url';
const client = new SuiGrpcClient({ network: 'testnet', baseUrl: 'https://fullnode.testnet.sui.io:443' })
  .$extend(walrus({ wasmUrl: walrusWasmUrl }));

// Or a CDN / self-hosted copy
walrus({ wasmUrl: 'https://unpkg.com/@mysten/walrus-wasm@latest/web/walrus_wasm_bg.wasm' });

// Next.js API routes (webpack and Turbopack)
const nextConfig: NextConfig = { serverExternalPackages: ['@mysten/walrus', '@mysten/walrus-wasm'] };

---

HTTP API エラー

413 Payload Too Large

原因： パブリッシャーにはリクエスト本文の最大サイズが設定されています。公開テストネットのパブリッシャーでは、アップロードの上限は約 10 MiB です。

対処方法：

• パブリッシャーの上限を超えるファイルには、CLI、TypeScript SDK を使用するか、独自のパブリッシャーを実行してください。
• メインネットには公開パブリッシャーがありません。アップロードリレーまたは SDK を直接使用してください。

---

アグリゲーターからの 503 BLOB_UNAVAILABLE

原因： blob が一時的に取得できない状態です（v1.47 以降、アグリゲーターはこの場合に 500 ではなく、再試行可能な 503 を返します）。

対処方法： 指数バックオフで再試行してください。問題が続く場合は、walrus blob-status --blob-id <BLOB_ID> を確認してください。blob の有効期限が切れているか、認証されていない可能性があります。

---

アップロード直後の 404 Not Found

原因： アグリゲーターの CDN キャッシュです。アグリゲーターの CDN に、blob が伝播する前の 404 がキャッシュされています。

対処方法： 指数バックオフで再試行してください。認証後、数秒から数分以内に blob を利用できるようになります。CDN 経由のアグリゲーターを使用している場合、遅延はキャッシュの TTL によって決まります。

---

Move 統合エラー

VMVerificationOrDeserializationError in command 0

原因： 公開済みの Move パッケージがオンチェーンの Walrus コントラクトと一致していません。これはほぼ常に Move.toml の依存関係の問題です。

修正方法： 次の順に確認してください。

1. ネットワークに対する subdir の指定が間違っています。 Testnet では testnet-contracts/walrus、mainnet では contracts/walrus を使用します。

   # Testnet
   Walrus = { git = "https://github.com/MystenLabs/walrus.git", rev = "testnet", subdir = "testnet-contracts/walrus" }
   
   # Mainnet
   Walrus = { git = "https://github.com/MystenLabs/walrus.git", rev = "main", subdir = "contracts/walrus" }
   

2. rev の指定が間違っています。 コミットはオンチェーンにデプロイされているものと一致している必要があります。testnet では testnet ブランチ、mainnet では main ブランチを使用するか、特定のコミットを指定してください。

3. Move.lock が古くなっています。 Move.lock を削除して、再ビルドしてください：rm Move.lock && sui move build。

4. edition の指定が間違っています。 "2024.beta" ではなく、edition = "2024" を使用してください。2024 edition では Sui フレームワークが暗黙的に解決されます。明示的な Sui = { git = ... } の指定が Walrus パッケージのフレームワークバージョンと一致しないと、依存関係の解決エラーが発生します。この指定を削除してください。

---

system::inner_mut による EWrongVersion（abort code 1）

原因： Walrus のアップグレード後に、古いパッケージ ID を使って Walrus システム関数を呼び出しています。Walrus はバージョン管理された共有オブジェクトを使用します。

修正方法：

• CLI または SDK を使用している場合： 最新バージョンに更新してください。クライアントがパッケージ ID を自動的に更新します。
• コントラクトを直接呼び出している場合： system_object を照会して、現在のパッケージ ID を確認してください。パッケージ ID をハードコードしないでください。
• Walrus クライアントのコードには再試行ロジックが組み込まれています。EWrongVersion が発生すると、refresh_package_id() を呼び出して再試行します。

---

Seal のエラー

Transaction was not signed by the correct sender

原因： Seal に渡された PTB に tx.setSender(address) が設定されていないか、送信者が復号するアドレスと一致していません。

修正方法：

tx.setSender(address);  // Must match the decrypting wallet address

---

ネットワーク／一般的なエラー

client/server api version mismatch

原因： インストールされている walrus バイナリのバージョンが、ネットワークで要求されるバージョンと一致していません。

修正方法：

suiup update walrus
# or install the version matching your network
suiup install walrus@mainnet

---

ルール

1. Move のエラーが発生した場合は、まず Move.toml を確認してください。 VMVerificationOrDeserializationError は、ほぼ常に依存関係の問題です。
2. 「gas coin」エラーが発生した場合は、トークン残高を確認してください。 書き込み操作には SUI と WAL の両方が必要です。
3. ブラウザーアプリでは、アップロードリレーを設定してください。 ブラウザーで SDK の書き込み操作を行うには、アップロードリレーが必要です。
4. 依存関係のリビジョンを切り替えるときは、Move.lock を削除してください。 古いロックファイルはビルドエラーの原因になります。
5. ネットワーク接続と設定の確認には、walrus info を使用してください。 walrus info が動作する場合、設定は正しいです。
6. バージョン不一致エラーが発生した場合は、CLI を更新してください。 suiup update walrus を実行してください。