Error codes

Every failure the Gofasta CLI reports carries a stable, machine-readable code. Codes exist so that scripts, CI steps, and AI coding agents can branch on what went wrong without pattern-matching English error text that may be reworded later.

Where codes appear

In text mode the code is printed alongside the message and a remediation hint. Under --json, stdout carries the error object:


{
  "code": "DEV_PORT_IN_USE",
  "message": "port 8080 is already in use",
  "hint": "another process is already bound to the configured PORT; stop it, pick a different port with `--port`, or update `server.port` in config.yaml",
  "docs": "https://gofasta.dev/docs/cli-reference/dev"
}

hint and docs are looked up from the code registry, so the same code always produces the same remediation guidance regardless of which command raised it. Both fields are omitted when empty.

Stability guarantee

A code is part of the CLI’s public interface. Once shipped it is never renamed — a code that stops being useful is deprecated in favor of a successor rather than repurposed. Automation can safely hard-code the strings below.

Unregistered codes still produce usable errors, just without a hint or docs link. INTERNAL is reserved for unexpected failures that indicate a bug in the CLI itself rather than anything wrong with your project — those are worth reporting.

The codes

General

Code	What it means and how to recover	Reference
`INTERNAL`	file a bug at https://github.com/gofastadev/cli/issues with the full command output	—

Project lifecycle

Code	What it means and how to recover	Reference
`NOT_GOFASTA_PROJECT`	run this command from the root of a gofasta project (directory containing go.mod plus the scaffolded app/ directory)	docs
`PROJECT_DIR_EXISTS`	choose a different project name or remove the existing directory	docs
`INVALID_NAME`	project names must be a valid Go module path (lowercase letters, digits, dots, slashes, hyphens)	docs

go / go.mod

Code	What it means and how to recover	Reference
`GO_MOD_INIT_FAILED`	make sure Go 1.25.0 or later is installed and on $PATH; run `go version` to check	docs
`GO_MOD_TIDY_FAILED`	run `go mod tidy` manually and inspect the output; a transitive dep may be unavailable or the module proxy may be unreachable	docs
`GOFASTA_INSTALL_FAILED`	wait 5–30 minutes for sum.golang.org to index a freshly-published release and re-run `gofasta new`; the CLI installs the exact gofasta library version it was tested against, so no manual `go get` is needed	docs
`GO_BUILD_FAILED`	the generated or edited Go code does not compile; fix the error above and re-run	—
`GO_TEST_FAILED`	one or more tests failed; inspect the output above for the specific failure	docs
`GO_VET_FAILED`	`go vet` flagged a static issue; address the warnings above and re-run	—
`GO_FMT_FAILED`	run `gofmt -s -w .` to apply formatting	—
`GO_LINT_FAILED`	`golangci-lint` reported issues; run `golangci-lint run` for full output	—

Wire / codegen

Code	What it means and how to recover	Reference
`WIRE_MISSING_PROVIDER`	add the provider to a provider set in app/di/providers/, then run `gofasta wire` to regenerate	docs
`WIRE_GENERATION_FAILED`	Wire failed to generate — inspect the error above; common causes are a missing provider, a type mismatch, or a circular dependency	docs
`GENERATOR_FAILED`	the generator could not complete; inspect the error above and verify the project layout is intact	docs
`PATCHER_FAILED`	the patcher could not locate an expected marker in a target file; verify you have not heavily modified the generated scaffold files	docs
`SWAGGER_GENERATION_FAILED`	run `gofasta swagger` manually to inspect the error; usually caused by malformed Swagger annotations on controller methods	docs
`GQLGEN_GENERATION_FAILED`	run `go tool gqlgen generate` manually to inspect the error; usually caused by a malformed .gql schema file	docs

Database / migrations

Code	What it means and how to recover	Reference
`MIGRATION_FAILED`	inspect the SQL error above; ensure the database is reachable and the migration file is valid	docs
`MIGRATION_DIR_MISSING`	create db/migrations/ or generate a migration with `gofasta g migration`	docs
`SEED_FAILED`	a seeder returned an error; inspect the output above	docs
`DATABASE_UNREACHABLE`	verify the database is running and the `database` section of config.yaml matches; test with `gofasta doctor`	docs
`DATABASE_RESET_FAILED`	`gofasta db reset` could not complete; inspect the step that failed above	docs

Deploy

Code	What it means and how to recover	Reference
`DEPLOY_HOST_REQUIRED`	set `deploy.host` in config.yaml or pass —host user@server	docs
`DEPLOY_CONFIG_INVALID`	the deploy configuration is invalid; run `gofasta doctor` or check config.yaml against the schema	docs
`SSH_FAILED`	verify your SSH key is authorized on the server and the host/port are reachable — test with `ssh -p <port> user@server echo ok`	docs
`HEALTH_CHECK_FAILED`	the deployed app did not respond at the health endpoint within the timeout; gofasta automatically rolled back to the previous release (first deploys are left in place) — inspect logs with `gofasta deploy logs`	docs
`DOCKER_COMMAND_FAILED`	a Docker command failed; check that Docker is running locally and on the remote host (run `gofasta deploy setup` to install it remotely)	docs
`ROLLBACK_FAILED`	rollback could not complete; inspect the step that failed above — the current release is unchanged	docs

Introspection / utility

Code	What it means and how to recover	Reference
`ROUTES_DIR_MISSING`	app/rest/routes/ was not found — run this command from the root of a gofasta project	docs
`CONFIG_INVALID`	config.yaml is malformed; validate it against the schema emitted by `gofasta config schema`	docs
`CONFIG_NOT_FOUND`	config.yaml not found in the current directory	docs
`FILE_IO`	could not read or write a file; check filesystem permissions	—

Verify / preflight

Code	What it means and how to recover	Reference
`VERIFY_FAILED`	`gofasta verify` reported a failing check above; fix the first failure and re-run	—

AI installer

Code	What it means and how to recover	Reference
`UNKNOWN_AGENT`	run `gofasta ai list` to see supported agents	—
`AI_MANIFEST_IO`	could not read or write .gofasta/ai.json; check filesystem permissions	—
`AI_INSTALL_FAILED`	one or more agent configuration files could not be written; inspect the error above	—
`AI_AGENT_CONFLICT`	another AI agent is already installed in this project; re-run with `--switch` to replace it, or `gofasta ai uninstall <agent>` to remove it first	—

Debug (gofasta debug)

Code	What it means and how to recover	Reference
`DEBUG_APP_UNREACHABLE`	the target app is not reachable at the resolved URL — start it with `gofasta dev` or pass `--app-url=http://host:port` if it runs on a different address	docs
`DEBUG_DEVTOOLS_OFF`	the app is running without the `devtools` build tag — rebuild under `gofasta dev` (which sets GOFLAGS=-tags=devtools) so /debug/* endpoints become available	docs
`DEBUG_TRACE_NOT_FOUND`	the requested trace is not in the ring — it may have been evicted (rings hold at most 50 traces); re-issue the request you want to inspect and try again	docs
`DEBUG_BAD_FILTER`	a filter value was rejected; see the command’s —help for accepted syntax	docs
`DEBUG_BAD_DURATION`	duration values use Go’s time.ParseDuration syntax — e.g. `100ms`, `2s`, `1m30s`	docs
`DEBUG_PROFILE_UNSUPPORTED`	supported profile kinds: cpu, heap, goroutine, mutex, block, allocs, threadcreate, trace	docs
`DEBUG_EXPLAIN_FAILED`	EXPLAIN is SELECT-only and requires the app to have registered its *gorm.DB via devtools.RegisterDB — verify the app was built with the devtools tag	docs

Dev server (gofasta dev)

Code	What it means and how to recover	Reference
`DEV_DOCKER_UNAVAILABLE`	install Docker Desktop (or Docker Engine + docker compose plugin) and make sure the daemon is running — test with `docker info`	docs
`DEV_COMPOSE_NOT_FOUND`	a compose.yaml is required for service orchestration; re-run with `--no-services` to skip Docker and run Air against an externally-managed database	docs
`DEV_SERVICE_UNHEALTHY`	a compose service did not become healthy within the timeout; tail its logs with `docker compose logs <service>`, or raise `--wait-timeout`	docs
`DEV_MIGRATION_FAILED`	`migrate up` returned a non-zero exit; inspect the SQL error above or re-run with `--no-migrate` to skip and investigate the DB state manually	docs
`DEV_AIR_NOT_INSTALLED`	Air is not registered on the project toolchain; run `go get github.com/air-verse/air@latest && go mod edit -tool github.com/air-verse/air`	docs
`DEV_PORT_IN_USE`	another process is already bound to the configured PORT; stop it, pick a different port with `--port`, or update `server.port` in config.yaml	docs
`DEV_FLAG_CONFLICT`	two flags requested incompatible behavior — see the message above; run `gofasta dev --help` for the flag matrix	docs
`DEV_LOCAL_REPLACE`	filesystem-path replaces (e.g. `replace ... => ../foo`) only resolve on the host — the docker build context cannot see paths outside the project. Either run without —all-in-docker (host mode handles local replaces fine), drop the replace and `go get` a published version, or vendor with `go mod vendor` so the replaced module is bundled into the build context.	docs
`DEV_SERVICE_UNKNOWN`	the name passed to —services is not declared in compose.yaml; check `docker compose config --services` for the list of valid names	docs
`DEV_PREFLIGHT_CANCELED`	preflight was canceled by the user (menu option [4]) or aborted on a non-TTY session — resolve the unreachable dependency manually, then re-run `gofasta dev`	docs

Upgrade (gofasta upgrade)

Code	What it means and how to recover	Reference
`UPGRADE_VERIFICATION_FAILED`	could not verify the downloaded binary against the release checksums.txt — retry, or download and verify the release asset manually before installing	docs
`INTERACTIVE_ONLY`	this command requires an interactive terminal and cannot run in —json / headless mode; drop —json or invoke a non-interactive equivalent	docs

Cross-resource impact analysis (gofasta xrefs / impact)

Code	What it means and how to recover	Reference
`SYMBOL_NOT_FOUND`	the symbol was not found in the current module — check the spelling and package qualifier (e.g. `pkg.Func` or `pkg.Type.Method`)	docs
`TYPE_ANALYSIS_FAILED`	go/packages could not type-check the module; run `go build ./...` to surface the underlying compile error	docs
`PACKAGE_LOAD_FAILED`	one or more packages failed to load — fix the build error above before running impact analysis	docs
`AMBIGUOUS_SYMBOL`	the unqualified symbol matches definitions in multiple packages; pass the fully qualified name (e.g. `irodata/app/services.OrderService.Archive`)	docs

Change-scoped verify (—since / —changed)

Code	What it means and how to recover	Reference
`GIT_NOT_AVAILABLE`	this directory is not a git repository — run `git init` or drop the —since/—changed flag	docs
`GIT_DIFF_FAILED`	`git diff` returned an error; check that the ref exists locally (`git fetch` may be needed) and that you have read access to the repo	docs
`GIT_REF_NOT_FOUND`	the supplied git ref does not resolve — try `git fetch origin` or pass a known commit / branch / tag	docs

Modify-aware generators (g method / g field / g endpoint / …)

Code	What it means and how to recover	Reference
`RESOURCE_NOT_FOUND`	no files match the given resource name — check spelling (PascalCase, singular) or run `gofasta g scaffold <Name>` to create it first	docs
`METHOD_ALREADY_EXISTS`	a method with that name already exists on the target interface — pick a different name or skip this generator	docs
`FIELD_ALREADY_EXISTS`	the model already has a field with that name — pick a different name or remove the existing field first	docs
`ROUTE_ALREADY_EXISTS`	that METHOD + path combination is already registered — pick a different path or use `gofasta g middleware` to attach behavior	docs
`AST_PARSE_FAILED`	the target Go file has a syntax error and cannot be parsed — fix the error above and re-run	docs
`AST_PATCH_FAILED`	could not locate the AST insertion target (e.g. interface or struct named for the resource) — the file may have been heavily restructured; inspect manually	docs

Migration safety preview (gofasta migrate up —explain)

Code	What it means and how to recover	Reference
`MIGRATION_LINT_FAILED`	static SQL analysis errored on a pending migration — inspect the file for malformed SQL or unsupported syntax	docs
`MIGRATION_PARSE_FAILED`	could not split the migration into statements — check for unmatched `$$` dollar-quote blocks or stray string literals	docs

Mock regeneration (gofasta g mock)

Code	What it means and how to recover	Reference
`INTERFACE_NOT_FOUND`	no interface with that name was found under app/services/interfaces/ or app/repositories/interfaces/ — check spelling or pass —all to refresh every mock	docs
`MOCK_GEN_FAILED`	the mock template failed to render — inspect the error above; often caused by an interface that uses unsupported features (generics, embedded external interfaces)	docs
`MOCK_DRIFT`	the on-disk mock no longer matches the interface — run `gofasta g mock --all` to regenerate, then commit the result	docs

Job / task introspection (gofasta inspect-jobs / inspect-tasks)

Code	What it means and how to recover	Reference
`JOBS_DIR_MISSING`	app/jobs/ was not found — generate a job with `gofasta g job <name> "<cron>"` first, or run this command from the project root	docs
`TASKS_DIR_MISSING`	app/tasks/ was not found — generate a task with `gofasta g task <name>` first, or run this command from the project root	docs

Debug replay (gofasta debug replay)

Code	What it means and how to recover	Reference
`DEBUG_REPLAY_NOT_FOUND`	the request id is not in the capture ring — it may have been evicted (rings hold at most 200 requests); re-issue the request you want to replay	docs
`DEBUG_REPLAY_FAILED`	the replayed request failed at the target app — inspect the response payload above or check the app logs	docs
`DEBUG_REPLAY_UNSAFE`	the replay override was rejected by the SSRF guard — overrides may change path / headers / body but cannot change scheme, host, or port	docs

Debug stack resolver (gofasta debug stack)

Code	What it means and how to recover	Reference
`DEBUG_STACK_PARSE_FAILED`	the stack frame does not match the expected `file:line function` format — verify the source is a gofasta-captured stack (TraceSpan.Stack or ExceptionEntry.Stack)	docs
`DEBUG_SOURCE_UNAVAILABLE`	the source file referenced in the stack frame is not present on disk (deleted, vendored, or outside the current module) — the frame is still resolvable but without source context	docs

Refactor (gofasta refactor feature-package)

Code	What it means and how to recover	Reference
`REFACTOR_INELIGIBLE`	not in a gofasta project, or already in the target layout — run `gofasta refactor status` to see where you actually are	docs
`REFACTOR_ABORTED`	the migration started but the post-move `go build` failed — `git restore .` to revert, then investigate; the output shows which files moved before the failure	docs
`REFACTOR_DIRTY_TREE`	the git working tree has uncommitted changes — commit, stash, or pass `--force`	docs
`REFACTOR_RESOURCE_NOT_FOUND`	the named resource doesn’t have a file at the expected source path — spell the resource name correctly (PascalCase), or use `--all`	docs
`REFACTOR_PRECHECK_FAILED`	the eligibility preflight found blocking conditions (torn per-resource state, unparseable files the migration must transform, a non-scaffold-shaped `gqlgen.yml`) — nothing was changed; fix the listed findings and re-run. `gofasta refactor status` re-checks eligibility. Not overridable	docs
`REFACTOR_NO_GIT`	the project is not a git repository, so an aborted migration cannot be reverted — `git init && git add -A && git commit` first, or pass `--force` to accept the risk	docs

gofasta init
Initialize a cloned or existing Gofasta project by installing dependencies and running code generators.
gofasta dev
Bring the full local environment up with one command — compose services + migrations + Air hot reload, with interactive restart.
gofasta debug
CLI surface for the devtools /debug/* endpoints — requests, SQL, traces, logs, errors, cache, pprof, EXPLAIN, HAR, plus the composed...
gofasta ai
Install per-agent configuration for Claude Code, Cursor, OpenAI Codex, Aider, and Windsurf — permission allowlists, hooks, project rules, and slash commands.
gofasta verify
Run the full preflight gauntlet — gofmt, vet, golangci-lint, tests, build, Wire drift, routes — in one command.
gofasta test
Run go test against the project with gofasta defaults — race detector on, every package, live output, plus shortcuts for short/integration/coverage/run-pattern.
gofasta status
Report the health of the current project — Wire drift, swagger drift, pending migrations, uncommitted generated files, module freshness.
gofasta inspect
Show the full composition of a resource — model fields, DTOs, service methods, controller methods, routes — as structured output.
gofasta inspect-jobs
Static AST scan of app/jobs/ that lists every registered cron job with its schedule from config.yaml.
gofasta inspect-tasks
Static AST scan of app/tasks/ that lists every async task with its wire name, payload shape, and handler/enqueuer presence.
gofasta impact
Reverse-dependency analysis — given a file or import path, list every package that depends on it (directly + transitively) and every Go source file in those packages.
gofasta xrefs
Type-aware reverse symbol lookup — find every reference to a Go func, type, method, var, or const across the current module.
gofasta do
Run a named development workflow — a pre-defined chain of gofasta commands that together accomplish one higher-level task.
gofasta config
Inspect and validate your project's config.yaml — currently the schema emitter, more subcommands to come.
gofasta serve
Run the project's HTTP server in production mode — no Air, no hot reload.
gofasta refactor
Switch a Gofasta project between layered and feature-package layouts without rewriting code by hand.
gofasta migrate
Run database migrations up or down for your Gofasta project, with static analysis (--explain), safe rollbacks (--steps, --all), and dirty-state repair (migrate repair).
gofasta seed
Run database seeders to populate your database with initial or test data.
gofasta db
Destructive database utilities, kept separate from `gofasta migrate` on purpose.
gofasta deploy
Deploy a Gofasta application to a remote VPS via SSH using Docker or a compiled binary, with a health gate and automatic rollback.
gofasta wire
Regenerate Google Wire dependency injection code for your Gofasta project.
gofasta swagger
Generate OpenAPI/Swagger documentation from the `@Summary`, `@Tags`, `@Router`, and `@Param` annotations the scaffold and `g endpoint` emit.
gofasta routes
Print every registered REST route in the project as a formatted table — method, path, and source file.
gofasta console
Start an interactive Go REPL in your project directory, powered by yaegi, for one-off data inspection and exploring an API surface without writing a throwaway main().
gofasta doctor
Check system prerequisites, project configuration, and database connectivity.
gofasta upgrade
Self-update the Gofasta CLI to the latest GitHub release.
gofasta version
Print the CLI version, the Go toolchain it was compiled with, and the OS/architecture target.
gofasta doctor
Check prerequisites, project configuration, and database connectivity before debugging a code.
gofasta verify
The preflight gauntlet that surfaces the GO_*, VERIFY_*, and GIT_* codes.