Skip to main content

Troubleshooting

This guide helps you diagnose issues when working with ZecKit locally or in CI. It’s written as a small mental model plus a repeatable debugging flow, not just a list of error fixes.

Understanding ZecKit (before you debug)​

What ZecKit does​

ZecKit helps you run a local Zcash devnet environment (typically via Docker), along with supporting services like nodes, a faucet, a miner, and an indexer (depending on your backend).

It also provides a built-in check command:

zeckit test

What ZecKit does not do​

ZecKit does not:

  • Run your application logic
  • Define your product’s test cases
  • Replace your CI “build + test” steps
Separation of responsibilities

ZecKit provides blockchain/devnet infrastructure. You provide the application and the tests that validate it.

Standard debugging flow (use this order)​

  1. Check health:
zeckit status
  1. Run a stricter check (when available):
zeckit test --check
  1. Confirm Docker is actually running and containers exist:
docker ps
  1. If state looks corrupted, inconsistent, or “stuck”, reset:
zeckit down --purge
zeckit up --fresh
Purge is destructive

--purge clears local devnet state/volumes. Only use it when you intentionally want a clean slate.

Reading zeckit status​

Example output​

zeckit-faucet-lwd-1       Up (healthy)
zeckit-lightwalletd-1     Up (unhealthy)
zeckit-zebra-miner-1      Up (healthy)
zeckit-zebra-sync-1       Up (unhealthy)

Zebra Miner - Height: 8959
Zebra Sync  - Height: 0
Faucet - Balance: 125.00 ZEC

How to interpret common signals​

SignalWhat it usually means
healthyService is ready enough for its role
unhealthyStill initializing or failed / blocked on a dependency
Miner height increasingBlocks are being produced
Faucet balance is positiveThere are funds available for testing
tip

“Unhealthy” often means still starting. Give the system time, then re-run zeckit status before you purge state.

Devnet fails to start​

Symptoms​

  • zeckit up appears to hang
  • timeout errors
  • docker ps shows no expected containers

Common causes​

  • Docker isn’t running
  • machine is resource constrained
  • corrupted local state from a previous run

Fix​

zeckit down --purge
zeckit up --fresh

If it still fails, confirm prerequisites:

Docker issues​

Docker isn’t running​

docker ps

If this errors, start Docker Desktop (macOS/Windows) or your Docker daemon (Linux).

Permission denied connecting to Docker (Linux)​

If you see errors about permission denied talking to the Docker socket:

sudo usermod -aG docker "$USER"

Then log out and back in (or reboot). Alternatively, use a rootless Docker setup per Docker’s docs.

Port conflicts​

Ports commonly involved​

AreaPortNotes
Zebra RPC8232Exact usage can vary by setup
HTTP services8080Often used by faucet / local HTTP endpoints
Indexer / metrics9067Varies by backend

Symptoms​

  • “address already in use”
  • services fail to bind ports

Fix​

Identify what’s listening (example on macOS/Linux):

lsof -i :8080

Stop the conflicting process, or tear down ZecKit containers:

zeckit down

Slow startup​

Why it happens​

Blockchain devnets need time to:

  • start multiple containers
  • initialize/sync state
  • produce blocks and fund faucets

What to do​

  • Wait and re-check zeckit status
  • If startup times out, increase the wait (if your CLI supports it), e.g.:
zeckit up --timeout 900

If you’re unsure which flags your version supports, run:

zeckit up --help
tip

The first run after a purge is often the slowest.

Services show “unhealthy”​

Example​

lightwalletd (unhealthy)
zebra-sync   (unhealthy)

Meaning​

  • still initializing, or
  • blocked waiting on a dependency, or
  • failed and needs a reset

Fix​

  1. Wait 1–2 minutes
  2. Re-check:
zeckit status

If it persists:

zeckit down --purge
zeckit up --fresh

Zebra sync height stays at 0​

This usually means the sync node hasn’t progressed yet (or the devnet is stuck).

What to try​

  • wait for miner activity and re-check zeckit status
  • inspect logs for miner/sync containers (names vary by setup):
docker ps
docker logs zeckit-zebra-miner-1
  • if still stuck, reset:
zeckit down --purge
zeckit up --fresh

Faucet balance is 0​

Common causes​

  • blocks aren’t being produced yet
  • services aren’t fully ready

What to try​

docker logs zeckit-zebra-miner-1
zeckit status

If it won’t recover:

zeckit down --purge
zeckit up --fresh

Tests failing​

Quick checks​

zeckit status
zeckit test --check

If the devnet looks healthy but tests still fail​

That often points to your application/test logic, not ZecKit itself. Validate locally:

zeckit up
# run your normal integration test command

CI failures​

Symptom: “not ready” / startup timeout​

In GitHub Actions, increase the action’s startup budget (example field name varies by workflow):

startup_timeout_minutes: '25'

More detail:

Symptom: devnet is ready, but CI tests fail​

Treat it like a normal test failure: reproduce locally with zeckit up and run the same test command your CI runs.

Cannot connect to the devnet from your app​

Checklist​

zeckit status
docker ps

Then verify your app is pointing at the correct host/port for your setup (localhost vs container networking).

“Weird” inconsistent behavior / suspected corruption​

If things feel random/inconsistent after lots of experiments:

zeckit down --purge
zeckit up --fresh

Resource issues​

Symptoms​

  • containers exit
  • frequent OOM kills
  • extremely slow progress

Fix​

  • increase Docker CPU/memory limits
  • close heavy apps
  • restart Docker
success

If you follow the standard flow (status → test --check → docker ps → reset), you can resolve most ZecKit issues without guessing.