Skip to main content

AI Troubleshooting & Error Codes

Always pass --json when diagnosing failures so HardKAS prints the stable code field.

Error CodeRoot CauseDiagnostic CommandSafe Recovery
RPC_CONNECTION_FAILED / RPC_INFO_UNAVAILABLENode not running, wrong port (18210 default for toccata-v2, or custom port in hardkas.config.ts), or missing --rpclisten-json.hardkas rpc health --network simnet --jsonStart localnet (hardkas localnet start --profile toccata-v2) or verify docker ps and rpcUrl.
NODE_NOT_SYNCEDSimnet node has no peers and stopped receiving mined blocks.hardkas rpc info --network simnet --jsonStart or resume the CPU miner until Synced: yes.
NO_SPENDABLE_UTXOSAccount has 0 UTXOs, or only immature coinbase rewards (< 1,000 DAA on simnet).hardkas accounts balance <name> --network simnet --jsonFund the account or keep the miner running ~1,000 DAA (~1 minute) and retry.
TX_SEND_WAIT_FAILEDtx send --wait submitted the transaction (outcome: submitted), but confirmation did not finish within --wait-timeout (default 60 s).hardkas tx status <txId> --network simnet --jsonDo not resend blindly. Wait on the same txId: hardkas tx wait <txId> --until confirmed --network simnet --url <ws://...> --json.
INSUFFICIENT_FUNDS_UPSTREAMSpendable UTXOs do not cover amount + fee.hardkas rpc utxos <address> --network simnet --jsonReduce --amount or fund the account with more KAS.
ARTIFACT_HASH_MISMATCHArtifact JSON was edited after creation (contentHash mismatch).hardkas artifact inspect <file> --jsonDo not edit hashes manually; re-run from the last intact step (tx plan / tx sign).
REPLAY_MODE_UNSUPPORTEDreplay verify was called on a real-node (simnet / testnet-10) submission.hardkas tx status <txId> --network simnet --jsonReplay only covers simulated runs. Use tx status and artifact verify --require consensus.
SILVER_VALUE_INVALIDPassed a raw hex string for a SilverScript bytes constructor arg instead of a byte array.hardkas silver verify <compile.json> --args <args.json>Format as [{"kind":"bytes","value":[...]}] (for pubkey, use the 32-byte x-only key: compressed pubkey without byte 0).
MAINNET_CONNECTION_DISABLED / MAINNET_SIGNING_DISABLED / MAINNET_BROADCAST_DISABLED / SILVERSCRIPT_MAINNET_NOT_ENABLEDMainnet is intentionally blocked in this release.hardkas doctor --jsonSwitch --network to simnet (or simulated for local dry-runs).