Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Go: cannot find main module and where go.mod is looked up

The go command searched upward and found no module. Create it at the right level, join modules with go.work, and check GOMOD before guessing.

~5 min readGo
#Go#Modules#Build#Tooling
A go project folder missing its module plaque, an amber cannot find module plate and a cyan go mod init tool

Introduction & Quick Summary

go: cannot find main module, but found .git/config in /home/me/service; to create a module there, run: go mod init means the go command was run outside a module. Since Go 1.16 module mode is the default, so a directory without a go.mod is not a package at all: go build, go test and go run all refuse before compiling.

The error names the working directory, and that is usually the whole answer:

  • The command ran in the wrong directory. A repository root that contains several modules has no go.mod of its own.
  • go.mod was never created. A new project copied without it, or a scratch directory.
  • GO111MODULE=off switches back to GOPATH mode, where go.mod is ignored and this message appears in other forms.
  • A nested module takes over as the boundary, so running from the parent treats the child as an ordinary directory.
  • go.work is missing for a multi-module workspace, so the root has no module context.
MessageTypical causeFix
cannot find main module, but found .git/configRepo root, no go.modgo mod init at the right level, or cd into the module
go.mod file not found in current directory or any parentOutside any modulego mod init example.com/app
no required module provides packageModule present, dependency missinggo get or go mod tidy
cannot find module providing package with -mod=vendorVendor tree out of datego mod vendor
Works in one shell onlyGO111MODULE or GOFLAGS differencego env in both shells

Core Mechanics, Signatures & Reproducible Setup

A module is a directory tree rooted at a go.mod file. The go command walks upward from the current directory looking for that file; if it reaches the filesystem root without finding one, it prints the message and stops. The module path in go.mod is the import prefix for every package inside, and go.sum pins the hashes of dependencies.

The search stops at the first go.mod it finds, and a nested module is a wall: the parent cannot build or test the child's packages by path, because the child is a separate module with its own dependency graph. That is why a monorepo with services/api/go.mod fails when you run go test ./... from the root.

Reproduce it in an empty directory:

bash
mkdir scratch && cd scratch go build ./...
text
go: go.mod file not found in current directory or any parent directory; see 'go help modules'

Inside a Git repository the message is more helpful, because the tool recognises the checkout boundary:

bash
git init scratch && cd scratch go build ./...
text
go: cannot find main module, but found .git/config in /tmp/scratch; to create a module there, run: go mod init

Key Comparison Table

Three modes decide whether go.mod is consulted at all, and a mismatch between shells produces "it works on my machine".

ModeSelected bygo.mod neededBehaviour
Module modeDefault since Go 1.16YesResolves from go.mod and the module cache
GOPATH modeGO111MODULE=offNoResolves from $GOPATH/src
Workspace modego.work fileYes, per moduleuse directives join several modules

The fix depends on which boundary you actually want.

IntentCommandResult
Single module at the repo rootgo mod init example.com/appOne go.mod, ./... covers everything
One module per servicecd services/api && go mod init example.com/app/apiParent needs go.work to build all
Join existing modulesgo work init ./services/api ./libs/sharedA go.work at the root, no moving files
Just run an existing toolgo -C services/api build ./...Changes directory for one command

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Create the module in the right place

go mod init writes a go.mod in the current directory. The name matters: it is the import prefix other code will use, so use the repository path rather than a bare word.

bash
cd ~/src/service go mod init github.com/you/service go mod tidy go build ./...

go mod tidy is what populates require lines from the imports and removes the ones no longer used. Skipping it leaves a go.mod that compiles locally by accident and fails on a clean machine.

Verify what Go thinks the module is

When the directory looks right but the command still fails, ask Go directly instead of reasoning about symlinks and shells:

bash
go env GOMOD GOWORK GO111MODULE GOFLAGS
text
/home/me/src/service/go.mod /home/me/src/service/go.work auto

GOMOD prints /dev/null when the command runs outside a module, which is the definitive answer. An empty GOWORK means no workspace is active, and a non-empty GOFLAGS containing -mod=vendor explains failures that mention vendor directories.

Workspaces for several modules

A repository with two modules is a normal layout. Instead of moving files, declare a workspace at the root so both are visible to one command:

bash
go work init ./services/api ./libs/shared go work use ./cmd/cli cat go.work
text
go 1.23 use ( ./services/api ./libs/shared ./cmd/cli )

go.work is for local development and is usually not committed for a library repository, while applications often do commit it. Its go directive has to be at least the highest version among the modules, or go work sync complains.

Nested modules and ./...

./... does not cross a module boundary. Running it from the root of a repository whose only go.mod files live one level down prints matched no packages or the main-module error, and adding packages at the root does not help:

bash
# wrong: root has no go.mod go test ./... # right: run per module (cd services/api && go test ./...) && (cd libs/shared && go test ./...)

A Makefile target that loops over module directories is more honest than a workspace for CI, because CI should test what each module ships, not the union of local overrides.

GOPATH mode and the GO111MODULE trap

GO111MODULE=off makes the tool ignore go.mod entirely and look under $GOPATH/src. The error changes to cannot find package with a GOPATH-shaped path, and the fix is to unset the variable rather than to create files under GOPATH.

bash
go env -w GO111MODULE=on go env GO111MODULE

go env -w persists the value in the user's environment file, which is where a leftover from an old tutorial causes this weeks later. go env -u GO111MODULE removes the override and restores the default.

Module proxy problems look similar

Once the module exists, a different message appears: no required module provides package github.com/x/y; to add it: go get github.com/x/y. That is resolution, not module discovery, and the proxy can be the cause. Checking the proxy directly separates the two:

curl -s "https://proxy.golang.org/github.com/gin-gonic/gin/@v/list" | tail -3 GOPROXY=direct go mod download

If GOPROXY=direct works and the default does not, the corporate proxy is blocking proxy.golang.org; set GOPROXY in go env -w rather than in each shell.

Common Compilation/Runtime Mistakes & Version Gotchas

Running go mod init in a subdirectory that already has a parent module. It creates a nested module, and the parent then cannot build the child. Check go env GOMOD from both directories before deciding.

Committing go.sum without go.mod changes. A go.sum with entries that the module graph does not require triggers missing go.sum entry or updates to go.sum needed, which reads like a network problem. Run go mod tidy and commit both files.

Using a bare name as the module path. go mod init service compiles locally and breaks consumers, because import paths become service/.... Use the fully qualified repository path.

Assuming go run file.go needs a module. go run file.go works outside a module for a single file, so "it runs but go build fails" is expected. go build always needs a module context.

Editing go.work by hand with relative paths from another directory. use paths are relative to the go.work file, not to the shell. go work use ./path writes them correctly.

Ignoring the toolchain directive. A go.mod with toolchain go1.23.0 on a machine with Go 1.21 produces a different error about the toolchain, and Go may try to download it. GOTOOLCHAIN=local pins behaviour when downloads are blocked.

Version floor. Module mode is the default from Go 1.16; go work from Go 1.18; go -C from Go 1.20; toolchain directives from Go 1.21. Older versions silently ignore parts of the file.

The message always refers to the current directory, so the sequence is: pwd, then go env GOMOD, then decide whether to create, move, or join. When you compare two go.mod files across branches, the diff tool makes the require-block change obvious, and the environment variable formatter keeps GOFLAGS and GOPROXY values consistent across CI and local shells.

Official references: Go modules reference and Managing dependencies.

Official references

primary documentation

The Go documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Go guides

More in Go

All Go guides

The guides filed next to this one in Go, in library order.