Go "cannot find main module" - Fix in CI

By Kaveh Alemi·Latchkey

A go command needs a main module to operate on. When the working directory has no go.mod in it or any parent, Go has no module in scope and refuses.

What this error means

A command stops with "go: cannot find main module; see go help modules". In CI this usually means the job ran from the wrong directory, before checkout, or in a workspace where no module is active.

go: cannot find main module, but found .git/config in /home/runner/work/app
	to create a module there, run:
	go mod init

Diagnose it: module path, proxy, or checksum?

Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.

Terminal

# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS

# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module

# verify the module cache against go.sum
go mod verify

# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*

Common causes

Ran outside the module root

The go command executed from above the module or in an unrelated folder with no go.mod up the tree.

Checkout had not placed go.mod

A go command ran before actions/checkout, so the directory had no module files yet.

How to fix it

Run from the module root

Set working-directory to the folder that contains go.mod.
Confirm go.mod is present before any go command.

.github/workflows/ci.yml

- run: ls go.mod && go build ./...
  working-directory: service

Use a workspace when spanning modules

For multi-module repos, point GOWORK at the go.work file so a main module is in scope.

.github/workflows/ci.yml

export GOWORK=$PWD/go.work
go build ./...

How to prevent it

Set working-directory explicitly for modules in subfolders.
Always run actions/checkout before any go command.
Add a ls go.mod smoke check at the top of the job.

Frequently asked questions

What causes Go "cannot find main module"?

There are 2 common causes: ran outside the module root and checkout had not placed go.mod. The go command executed from above the module or in an unrelated folder with no go.mod up the tree.

How do I fix Go "cannot find main module"?

There are 2 fixes depending on which cause you have: run from the module root and use a workspace when spanning modules. Work through them in order, since the first is the most common.

What does Go "cannot find main module" actually mean?

A command stops with "go: cannot find main module; see go help modules".

How do I stop Go "cannot find main module" happening again?

Set working-directory explicitly for modules in subfolders. The prevention section lists 3 changes that keep it from recurring.