Fix it fast
Most likely: The command is running outside the intended module or under an unintended go.work file.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
go: go.mod file not found in current directory or any parent directory; see 'go help modules'
go: no modules were found in the current workspace; see 'go help work'Check the cause
Run focused checks to identify what is failing in this environment.
go version
go env GOMOD GOWORK
pwdApply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# Existing project
cd <module-root>
# New project only
go mod init <module-path>
# Tool install outside a module
go install <command>@<version>Verify it works
Repeat the relevant checks and confirm the original error is gone.
# Existing or new project
go env GOMOD GOWORK
go list -m
go build ./...
# Tool installation outside a module
go install <command>@<version>Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not create a throwaway
go.modin an unrelated parent directory. - Do not add
replacedirectives until the active module boundary is correct.
What This Error Means
Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.
How to Fix It
The fastest fixes here come from checking the immediate failing layer before you change anything unrelated. Make one correction at a time and re-test from the same environment.
Wrong directory:change to the module root and set the CI working directory explicitly.
New project:run go mod init <module-path> only after choosing the permanent import path. This creates go.mod
Unintended workspace:run the command with GOWORK=off or remove the inherited workspace setting from the job. Do not delete a shared go.work blindly.
Empty workspace:add the intended module with go work use <module-directory> and review the go.work diff.
Tool installation:use go install <command>@<version>
Why It Happens
The command is outside the checkout or at a repository root while the Go module is in a subdirectory.
This is a new project and no go.mod has been initialized yet.
An unexpected parent go.work is active, or the intended workspace has no usable use entries.
A script used go get or unversioned go install to install a tool outside a module.
Verify the Fix
Project build: confirm go env GOMOD GOWORK, run go list -m, then repeat the build, and tool installation: rerun go install <command>@<version> outside the module.
Confirm the working directory and active workspace
Run go version and go env GOMOD GOWORK in the failing shell, container, or CI step.
Find the intended go.mod. In CI, verify the checkout and working directory before changing files.
If GOWORK names a file, confirm its use directories exist in this checkout.
How Go selects the main module or workspace
This is the part worth understanding if the quick fix did not hold. It explains what Go is trying to do at the moment the error appears.
Build commands search the current directory and its parents for go.mod. If GOWORK selects a go.work, its use directives define the workspace modules.
Go stops before downloading dependencies or compiling. For tool installation outside a module, use go install <command>@<version>, not go get.
Prevent It From Coming Back
To prevent this, pin the working directory in CI and container stages, document whether the repository uses one module, nested modules, or a workspace, and pin tool installs with @<version> and keep them separate from application dependencies.
Docs and source code
Go module commands outside a module test
Current Go test coverage for exact no-go.mod messages and tool installation outside a module. - Source
The tests distinguish commands that need go.mod from go install with an explicit version.Go empty workspace test
Current test for the exact no-modules-in-workspace diagnostic. - Source
An active empty go.work file produces the no modules were found message.Go Modules Reference
Official reference for module files, version selection, proxies, private modules, checksums, workspaces, and vendoring. - Source
The go command uses module paths and versions to resolve, download, and authenticate dependencies.