ワンクリックで
hydra-head-troubleshooter
"Hydra troubleshooting: decision tree for common issues. Maps symptoms to fixes with verification steps."
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
メニュー
"Hydra troubleshooting: decision tree for common issues. Maps symptoms to fixes with verification steps."
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Read-only wallet state via cardano MCP: balances, addresses, and UTxOs. Requires a configured cardano MCP server.
Retrieve ADAHandle identities ($handle) for the connected wallet via cardano MCP. Read-only.
Query staking delegation status and available rewards via cardano MCP. Read-only, no delegation changes.
Sign and submit pre-built Cardano transactions via cardano MCP. High-risk: requires structured preview and explicit user confirmation.
"Aiken workflows: validators, building, blueprints, .plutus generation. Safe guidance for smart contract development."
"Diagnose cardano-cli: version, era-prefixed vs legacy syntax, network flags. Produces compatibility report."
| name | hydra-head-troubleshooter |
| description | Hydra troubleshooting: decision tree for common issues. Maps symptoms to fixes with verification steps. |
| allowed-tools | ["Read"] |
| user-invocable | true |
| context | ["!hydra-node --version 2>&1 | head -3"] |
| metadata | {"openclaw":{"emoji":"🐉","requires":{"anyBins":["hydra-node","docker"],"bins":["curl"]},"install":[{"id":"brew","kind":"brew","formula":"colima docker docker-compose curl","bins":["colima","docker","docker-compose","curl"],"label":"Install Docker runtime (Colima) + Docker CLI + Compose + curl (brew)","os":["darwin","linux"]}]}} |
If hydra-node is not installed locally, use the wrapper script in this skill folder to run hydra-node inside Docker (Hydra upstream recommends Docker images for quickest start).
chmod +x {baseDir}/scripts/hydra-node.sh
{baseDir}/scripts/hydra-node.sh --help
{baseDir}/scripts/hydra-node.sh gen-hydra-key --output-file hydra
For full multi-node Head demos, prefer the hydra.family Docker Compose demo (it's the canonical "known-good" setup).
# Check hydra-node version
hydra-node --version
# Check API health
curl -s localhost:4001/health
# Check peers
curl -s localhost:4001/peers
# Check head status
curl -s localhost:4001/status
# Check metrics (if enabled)
curl -s localhost:6001/metrics | grep hydra
Symptoms:
Check 1: Cardano connection
# Verify cardano-node is ready
cardano-cli query tip --testnet-magic 1
# Should show current slot, not error
# Check socket exists
ls -la $CARDANO_NODE_SOCKET_PATH
Fix: Wait for cardano-node sync, verify socket path and network magic
Check 2: Scripts tx id
# Verify you're using correct scripts tx id for network
# Get from hydra-node release notes
# In hydra-node logs, look for:
grep -i "script" hydra-node.log | head -20
Fix: Use correct --hydra-scripts-tx-id for your network
Check 3: Key mismatch
# Verify cardano.sk matches what peers have as your vkey
cardano-cli key verification-key \
--signing-key-file cardano.sk \
--verification-key-file check.vkey
# Compare check.vkey with what you distributed
Fix: Re-exchange verification keys with all peers
Symptoms:
Check 1: Peer connectivity
# In logs, look for PeerConnected
grep "PeerConnected" hydra-node.log
# Check metrics
curl -s localhost:6001/metrics | grep peers_connected
Fix: Verify --peer host:port is correct and ports are reachable
Check 2: Hydra key mismatch
# Look for AckSn issues
grep -E "AckSn|LogicOutcome" hydra-node.log
# Verify hydra keys match
hydra-node verify-keys \
--hydra-signing-key hydra.sk \
--hydra-verification-key peer-hydra.vk
Fix: Re-exchange hydra verification keys
Check 3: Version mismatch
# All nodes must run compatible versions
hydra-node --version
# Compare across all participants
Fix: Align hydra-node versions
Symptoms:
Cause: Different ledger views due to config drift or missed txs
Fix: Snapshot side-loading
# 1. Get latest snapshot from healthy node
curl -s http://healthy-node:4001/snapshot > snapshot.json
# 2. Post to out-of-sync node
curl -X POST http://out-of-sync-node:4001/snapshot \
-H "Content-Type: application/json" \
-d @snapshot.json
Verify: Snapshots resume, all parties sign again
Symptoms:
SnapshotAlreadySigned in logsReality:
SnapshotAlreadySigned is transient and harmless with mirrorsFix: Reduce mirror count or accept transient warnings
| Pattern | Meaning |
|---|---|
PeerConnected | Peer connected successfully |
PeerDisconnected | Peer lost connection |
AckSn | Snapshot acknowledgment |
LogicOutcome | Head logic result (check for errors) |
SnapshotConfirmed | Snapshot finalized |
HeadIsOpen | Head successfully opened |
HeadIsClosed | Head closed, contestation started |
After any fix:
User request: "My Hydra head won't open—stuck at commit"
Response:
# 1. Check all peers connected
grep "PeerConnected" hydra-node.log | tail -10
# Should see PeerConnected for each peer
# 2. If missing peers, check network
nc -zv peer-host 5001
# Should show "Connection succeeded"
# 3. Check all parties committed
curl -s localhost:4001/status | jq .
# Look for parties and their commit status
# 4. Check for key issues
grep -E "InvalidSignature|WrongParty" hydra-node.log
# Common fix: restart with correct peer addresses
# Verify --peer host:port matches actual peer locations
hydra-head (operational guidance)hydra-head-operator (execution)reference/sources.md (doc provenance)