Skip to main content
Start every investigation with stacksdapp doctor. Use stacksdapp doctor --strict in CI to fail on warnings.

​
Contents

​
Prerequisites

​
Project not found (exit 2)

  • cd to a directory containing stacksdapp.toml or contracts/Clarinet.toml
  • Or: stacksdapp --root /path/to/project <command>
  • For raw Clarinet repos: run stacksdapp init first

​
Deploy failures (exit 8)

​
Testnet / mainnet

​
Devnet

​
Devnet issues

​
Boot stuck

  1. Ensure Docker is running
  2. Stop conflicting containers: docker ps --filter name=devnet -q | xargs docker stop
  3. stacksdapp clean --force
  4. Retry stacksdapp dev --auto-deploy
  5. Do not run manual clarinet devnet start alongside stacksdapp dev

​
Stall after ~block 71

Known issue with long-running local devnet (PoX / signer timeout). Workarounds:
  • Deploy early: stacksdapp dev --auto-deploy
  • Use testnet for deploy verification
  • Full reset: stacksdapp clean --force, restart Docker, retry
Testnet and mainnet deploy are unaffected. See Local devnet.

​
Clarity version / epoch mismatch

  • C5 requires epoch = "3.4" (not "4.0")
  • C6 requires epoch = "4.0"
  • Regenerate plans: cd contracts && clarinet deployments generate --devnet
Or add with the correct version: stacksdapp add name --clarity-version 5 Full mapping: Clarity versions

​
Bindings out of sync

Never patch frontend/src/generated/* manually. See Code generation.

​
Check failed (exit 6)

Run stacksdapp check and fix Clarinet checker errors in .clar files.

​
use of undeclared trait <sip-010-trait>

Explorer or deploy abort when impl-trait uses a short trait name instead of a full on-chain contract path. Fix steps:
  1. Run stacksdapp add NAME --template sip010 (or sip009) instead of rewriting from blog snippets
  2. Match [[project.requirements]] in Clarinet.toml to the target network
  3. stacksdapp check → stacksdapp test → redeploy

​
Frontend errors

​
Cannot convert [object Object] to a BigInt

Common when formatting SIP-010 balances or other uint read-only results. Cause: Hook data from read-only calls uses cvToValue, which represents (ok uint) as { type: "uint", value: "1500000" } — not a native bigint. Fix: Do not BigInt(hook.data) directly. Unwrap the cvToJSON shape first. Full helpers and examples: Frontend guide.

​
Failed to fetch on read-only calls

Browser could not reach the Stacks node — not a contract revert. Checklist:
  1. cat frontend/src/generated/deployments.json — contract entry exists
  2. grep NEXT_PUBLIC_NETWORK frontend/.env.local — matches deploy network
  3. After testnet deploy: stacksdapp dev --network testnet (not default devnet)
  4. Guard read-only call() until wallet address is valid; show hook.error
Full patterns: Frontend guide

​
Tests failed (exit 7) / Generate failed (exit 10)

Tests:
Contract tests use simnet — no Docker. See Testing. Generate:
  • Validate contracts/Clarinet.toml
  • Run npm install in contracts/ and frontend/
  • stacksdapp clean --force then stacksdapp generate

​
Init conflicts

Merge duplicate settings/, tests/, or deployments/ directories before rerunning stacksdapp init.

​
Git hook blocked commit

The pre-commit hook blocks likely seed phrases in Testnet.toml and Mainnet.toml. Unstage real mnemonics before committing. Emergency bypass only:
Devnet template mnemonics are public — devnet only. Never reuse them on testnet or mainnet.

​
Getting help