Skip to content
Keel

Troubleshooting

1) keel: command not found

Section titled “1) keel: command not found”

Verify installation and PATH:

Terminal window
which -a keel
go env GOBIN
go env GOPATH

If installed with go install, add $(go env GOPATH)/bin to your PATH (when GOBIN is empty).

2) I have multiple versions of keel

Section titled “2) I have multiple versions of keel”
Terminal window
which -a keel
keel --version

Keep only one active installation method (go install, brew or manual binary).

3) I see a keel upgrade suggestion

Section titled “3) I see a keel upgrade suggestion”

In the current binary, the upgrade subcommand does not appear in keel --help.

Update with your actual method:

  • go install github.com/slice-soft/keel@latest
  • brew upgrade slice-soft/tap/keel
  • manual replacement from release

4) keel new ... fails

Section titled “4) keel new ... fails”

Common cases:

  • directory '<name>' already exists
  • project name cannot contain spaces
  • project name is required when using --yes/-y

Additionally, in post-setup these may fail:

  • go mod tidy (network/proxy)
  • git init or initial commit (git config)

5) keel generate doesn’t work in my project

Section titled “5) keel generate doesn’t work in my project”

Validate minimum structure:

  • go.mod
  • cmd/main.go
  • internal/

If missing, you’ll see:

keel generate must be executed inside a Keel project

6) keel generate fails due to existing files

Section titled “6) keel generate fails due to existing files”

Typical error:

file already exists: ...

For non-module types, the CLI does not overwrite files. Rename/delete manually or generate another component.

7) module package mismatch

Section titled “7) module package mismatch”

If you manually edited packages inside internal/modules/<module>/, this may appear:

module package mismatch: expected 'x', found 'y' in <file>

Align the package of the module’s files to the expected name.

8) keel run <script> says it doesn’t exist

Section titled “8) keel run <script> says it doesn’t exist”

Check keel.toml:

  • [scripts] must exist
  • the name must match exactly
  • the value cannot be empty

9) keel init does not complete Air installation

Section titled “9) keel init does not complete Air installation”

The CLI tries:

Terminal window
go install github.com/air-verse/air@latest

If it fails:

  1. install Air manually,
  2. verify that air is in PATH,
  3. open a new terminal.

10) Completion doesn’t work

Section titled “10) Completion doesn’t work”
  1. Run keel completion install.
  2. Verify that the shell file has the source line.
  3. Open a new session.

11) /docs doesn’t appear

Section titled “11) /docs doesn’t appear”

Behavior of ss-keel-core: if Env == "production", it does not mount GET /docs or GET /docs/openapi.json.

12) Port in use

Section titled “12) Port in use”

ss-keel-core tries to find the next available port from the configured one and reports it in the logs. Check the startup output to confirm the final port.

Quick diagnostic checklist

Section titled “Quick diagnostic checklist”
Terminal window
keel --version
keel --help
which -a keel
cat keel.toml
go test ./...

If the error persists, share:

  • exact command executed
  • complete error message
  • output of keel --version
  • relevant fragment of keel.toml