Fix the errors you hit starting a Go and Docker project
Almost every error in the first hour of a new project is one of about twenty, and none of them means you have done something stupid. They mean a tool is not installed, is not on your PATH, is not running, or is already holding the port you asked for.
Each section below is headed with the message as it actually appears, so you can match what is on your screen. Read the cause, not just the command: the same fix applied without understanding comes back a week later.
14 min read. Commands and output last run against Grit v3.560.0.
The three questions that solve most of them
Before searching for a specific message, answer these. They resolve a surprising proportion of what follows.
Did you open a new terminal?
Installing a tool changes your PATH. A shell that was already running kept the old one, so go, docker or pnpm will still look missing no matter how many times you reinstall. Close the terminal, open a new one, and check again. On Windows this includes the integrated terminal inside your editor: restart the editor.
Is the thing actually running?
Docker Desktop is an application. If it is not open, every docker command fails, and the message does not say "Docker Desktop is closed", it says something about a pipe or a socket. Open it and wait for the whale icon to stop animating.
Are you in the right directory?
Go commands read the go.mod in the current directory. Node commands read package.json. Half of the "cannot find module" family is a command run one level too high or too low. pwd, or cd on Windows, before anything else.
Go
go: command not found
Also 'go' is not recognized as an internal or external command on Windows. Go is not installed, or it is installed and its bin directory is not on your PATH.
Install Go 1.26.11 or newer from go.dev/dl. Then open a new terminal and run go version.
# macOS, with Homebrew$brew install go# Debian and Ubuntu: the apt package is usually years old.# Download the tarball from go.dev/dl instead, then:$sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go*.tar.gz$echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile# Windows: use the .msi installer, which sets PATH for you.
If go version works but a tool you installed with go install does not, that is a different PATH: add $(go env GOPATH)/bin, which is %USERPROFILE%\go\bin on Windows.
go.mod file not found in current directory or any parent directory
You are outside a Go module. Either you are in the wrong folder, or the module was never created.
# Are you where you think you are?$pwd && ls go.mod# No go.mod anywhere: create the module$go mod init example.com/myapp
In a project with the API in a subdirectory, which is the usual layout, the Go commands run from there: cd apps/api first.
package X is not in GOROOT
Go looked for your import among the standard library and did not find it. Nearly always a dependency that was never downloaded, or an import path with a typo.
$go mod tidy
That reads every import in your code, fetches what is missing, and removes what is no longer used. If it still fails, the import path itself is wrong: compare it against the package's own documentation, since the import path and the repository URL are not always the same string.
missing go.sum entry; to add it: go mod download
The module graph changed and go.sum, which records the checksum of every dependency, did not keep up. Usually after editing go.mod by hand or merging a branch.
$go mod tidy
Commit the resulting go.sum. It is not noise: it is what stops a dependency being swapped under you.
dial tcp: lookup proxy.golang.org: no such host
Go cannot reach the module proxy. No network, DNS blocked, or a corporate proxy intercepting it.
# Behind a company proxy with its own mirror$go env -w GOPROXY=https://your-mirror.example.com,direct# Or go direct to the source hosts$go env -w GOPROXY=direct GOSUMDB=off
Turning off GOSUMDB disables checksum verification, so use it to get unblocked and not as a permanent setting. On a VPN, try it disconnected first: that is the single most common cause.
Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work
The standard SQLite driver is a wrapper around C code and needs a C compiler. You get this on a machine without one, which on Windows is most machines.
Either install a compiler:
# Debian and Ubuntu$sudo apt install build-essential# macOS$xcode-select --install# Windows: install MSYS2 or TDM-GCC, then confirm$gcc --version
Or use the pure Go driver, which needs no compiler and has the same API:
$go get github.com/glebarez/sqlite# then change the import from gorm.io/driver/sqlite
listen tcp :8080: bind: address already in use
Another process holds the port. Almost always a server you started earlier and did not stop, often in a terminal tab you closed without stopping the process.
# macOS and Linux$lsof -ti:8080 | xargs kill# Windows PowerShell$Get-NetTCPConnection -LocalPort 8080 -State Listen |Select-Object -Expand OwningProcess |ForEach-Object { Stop-Process -Id $_ -Force }
On macOS, port 5000 is held by AirPlay Receiver and port 7000 by the Control Center. Those are not stray processes of yours, and killing them is not the fix: pick another port, or turn the feature off in System Settings.
panic: runtime error: invalid memory address or nil pointer dereference
Something you called a method on was nil. In a new project this is almost always a database handle or a service you forgot to construct before using, because the code compiles perfectly well either way.
Read the stack trace from the bottom up: the first line in your own package, not in a library, is where to look. The variable on that line is the nil one.
The habit that prevents it
Return an error from a constructor rather than returning a half-built value. A NewService() that cannot fail will happily hand you a struct whose database field is nil, and the crash arrives later, somewhere else.
Docker
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
On Windows the same thing reads error during connect: open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.
Docker Desktop is not running. Open it and wait until the icon settles. On Linux, where there is no Desktop app, start the service:
$sudo systemctl start docker$sudo systemctl enable docker # and at every boot
permission denied while trying to connect to the Docker daemon socket
Linux only. Your user is not in the docker group, so only sudo docker works.
$sudo usermod -aG docker $USER# then log out and back in, or:$newgrp docker
The group change applies to new sessions, which is why people add themselves and then report that it did not work.
Bind for 0.0.0.0:5432 failed: port is already allocated
Something already listens on that port: usually a Postgres you installed natively months ago and forgot, or another project's containers still up.
# Which container has it?$docker ps --format "table {{.Names}}\t{{.Ports}}"# Another project's stack, still running$docker compose -f ../other-project/docker-compose.yml down
If it is a native Postgres, either stop the service or move the container to a different host port. Change only the left-hand number, which is the host side:
services:postgres:ports:- "5433:5432" # host 5433, container still 5432
Then update the port in your .env too. Changing one and not the other is the follow-up error.
docker: 'compose' is not a docker command
You have an old Docker, where Compose was a separate program called docker-compose with a hyphen. Modern Docker has it built in as docker compose with a space.
Upgrade Docker, or use the hyphenated form. Do not install both and alternate between them: they keep separate state and will confuse you about what is running.
no space left on device
Docker accumulates images, stopped containers, build caches and dangling volumes. On a development machine it can reach tens of gigabytes without you noticing.
$docker system df # where it went$docker system prune # stopped containers, unused networks, dangling images
Do not run docker system prune --volumes casually. Volumes are where your database lives, and that flag deletes every one not attached to a running container. A stopped project loses its data.
database system is starting up / connection refused on first run
Your API started before Postgres finished initialising. Containers start in parallel, and a container being up is not the same as the service inside it being ready.
The fix is a healthcheck and a condition, not a sleep. depends_on alone waits for the container, not the database:
services:postgres:image: postgres:17-alpinehealthcheck:test: ["CMD-SHELL", "pg_isready -U postgres"]interval: 2stimeout: 3sretries: 15api:depends_on:postgres:condition: service_healthy
Node, npm and pnpm
pnpm: command not found
pnpm is not installed. The least surprising way is Corepack, which ships with Node and installs the exact version a project asks for.
$corepack enable$corepack prepare pnpm@10.33.4 --activate# or, without Corepack$npm install -g pnpm@10.33.4
Pin the version rather than taking the newest. A major pnpm release changes how the lockfile and node_modules are laid out, and a project installed with two different majors behaves differently on two machines.
Unsupported engine: wanted node >=20.9.0, current node v18.x
Your Node is older than the tooling accepts. Install Node 20.9 or newer. The least painful route is a version manager, because you will eventually need two versions on one machine.
# nvm, macOS and Linux$nvm install 22 && nvm use 22# fnm, which is faster and works on Windows too$fnm install 22 && fnm use 22
Module not found: Can't resolve '@/components/...'
The @ alias is a TypeScript path mapping, not something Node knows about. Either tsconfig.json does not define it, or the file genuinely is not there.
{"compilerOptions": {"paths": {"@/*": ["./*"]}}}
Check the case of the filename as well. macOS and Windows do not care about case and Linux does, so an import of Button against a file named button.tsx works on your laptop and fails in CI, which is a miserable way to find out.
Error: Cannot find module 'next' / ERR_MODULE_NOT_FOUND
Dependencies are not installed, or the install was interrupted and left node_modules half written. Start again from clean:
$rm -rf node_modules apps/*/node_modules$rm -f pnpm-lock.yaml # only if the lockfile itself is suspect$pnpm install
Deleting the lockfile is a bigger step than it looks: it lets every dependency move to a newer version at once. Try the install without deleting it first.
EADDRINUSE: address already in use :::3000
The Node version of the port problem, usually a dev server that survived a closed terminal. Kill it as above, or start on another port:
$pnpm dev --port 3005
Hydration failed because the server rendered HTML didn't match the client
Something rendered differently on the server and in the browser. Three causes cover nearly all of it: new Date() or Math.random() called during render, reading window or localStorage during the first render, and invalid HTML nesting such as a div inside a p, which the browser silently restructures.
For anything that genuinely only exists in the browser, read it in an effect after mounting rather than during render.
If you are using Grit
grit: command not found
The binary is not on your PATH. The installer puts it in ~/.grit/bin, which your shell only knows about after it has been added and the terminal reopened.
$echo 'export PATH=$PATH:$HOME/.grit/bin' >> ~/.zshrc # or ~/.bashrc$source ~/.zshrc$grit version
If grit version prints an older version than you installed, you have two copies and the wrong one is first on PATH. which -a grit, or where grit on Windows, lists every one it can see.
This does not look like a Grit project
Grit commands read grit.json at the project root. You are in a subdirectory, or in the wrong project. Move to the directory that contains it.
For the Grit-specific failures, generation, migrations, the admin build, the troubleshooting page in the documentation goes further, and grit doctor checks a project against the things that are commonly wrong without touching the network.
$grit doctor
Frequently asked questions
- Why does reinstalling the tool not fix "command not found"?
- Because the problem is usually PATH, not the installation. Your shell reads PATH once when it starts, so a terminal that was already open keeps the old value forever. Close it, open a new one, and check again before reinstalling anything.
- Is it safe to run docker system prune?
- Without flags, yes: it removes stopped containers, unused networks and dangling images, all of which rebuild. With
--volumesit also deletes volumes that no running container is using, and that is where your database lives. A project you stopped yesterday loses its data. - My port is in use but nothing is running. What is holding it?
- A process you cannot see in your terminal: a dev server whose window you closed without stopping it, a Docker container, or an operating system service. On macOS, ports 5000 and 7000 belong to AirPlay and Control Center. List what is listening with
lsof -i:PORT, orGet-NetTCPConnection -LocalPort PORTin PowerShell. - Should I develop inside WSL on Windows?
- If you are comfortable with it, yes. File watching and Docker are both faster, and most tutorials assume a Unix shell. Keep your code inside the Linux filesystem, under
~, rather than under/mnt/c: crossing the boundary makes every file read slow enough to notice, and file watching unreliable.
Next steps
- Build your first full-stack appGo, React and the agreement between them, with a checkpoint at every step.
- Postgres, Redis and MinIO with Docker ComposeWhat the compose file says, line by line, and the Windows-specific traps.
- Grit troubleshootingThe failures specific to generation, migrations and the admin build.
- grit doctorAn offline check of the things that are commonly wrong in a project.
