Troubleshooting
This page lists common issues and practical fixes.
crank is not found after installation
Check where the binary was installed and ensure that directory is on your PATH.
For Go installs:
go env GOPATH
Add the Go binary directory to your shell profile:
export PATH="$PATH:$(go env GOPATH)/bin"
Then verify:
crank --version
crank init fails during dependency installation
crank init runs go get and go mod tidy in the generated project. Failures are usually caused by:
- no network access
- private module proxy settings
- an unavailable Go proxy
- an old Go version
Try:
go version
go env GOPROXY
crank tidy --project ./myapp
If your environment requires direct module fetching:
go env -w GOPROXY=direct
migrate binary is missing
crank migrate attempts to auto-install golang-migrate. If that fails, install it manually:
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
Make sure Go’s binary directory is on your PATH.
crank migrate cannot determine the database URL
Provide one explicitly:
crank migrate up --database-url postgres://postgres:postgres@localhost:5432/myapp?sslmode=disable
Or set:
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/myapp?sslmode=disable
crank migrate up
Or ensure configs/config.yaml contains a valid database: section.
PostgreSQL connection refused
Make sure PostgreSQL is running and the database exists.
Common checks:
psql postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable
createdb myapp
Then run:
crank migrate up
Swagger docs are missing
Run:
crank swag
Then restart the server and open:
http://localhost:8080/swagger/index.html
If the swag binary is missing, crank should auto-install it. If not, install manually according to the message printed by crank.
crank make workflow or crank make activity fails
Temporal generators require the temporal feature.
Add it first:
crank add temporal --project ./myapp
Then retry:
crank make workflow OrderFulfillment --project ./myapp
Generated handler is not reachable
Run:
crank doctor
If handler wiring failed, inspect:
internal/adapters/http/web/routes.go
Generated handlers are usually registered automatically. If your routes file was heavily edited and markers were removed, crank may print a manual wiring hint instead of modifying the file.
file already exists
Generators avoid overwriting primary artifacts unless you pass --force.
crank make handler Product --force
Dependency files that already exist are skipped by design.
unknown feature
Run:
crank list
Then use the exact feature name, for example:
crank add qdrant --project ./myapp
GORM and Bun conflict
A project cannot have both ORM features.
Use one of:
crank init myapp --features=base,auth
crank init myapp --features=base,auth --use-bun
crank init myapp --features=base,auth,bun
Do not pass both gorm and bun.
crank doctor reports module path mismatch
Compare .crank.yaml and go.mod:
.crank.yaml module_path: github.com/acme/myapp
go.mod module github.com/acme/myapp
If you renamed the module, update both files consistently and run:
crank tidy
crank doctor
docmd build fails for the documentation site
From the crank repository root, run:
npx @docmd/core build
If npx cannot download packages, check Node/npm installation and network access:
node --version
npm --version
The site source is docs/, configured by docmd.config.json, and the output directory is dist/.
