Go

Fix Go "No Required Module Provides Package" — Module Resolution, Typos, Cycles, and the Replace Fix

An import names a package, and the build has to find that package somewhere: in the standard library, in the module you are standing in, or in a module your go.mod file requires. When none of those three places holds it, the build stops before it compiles anything and tells you which package it could not provide. Each section below takes one shape, shows the exact message it prints, and gives the fix that belongs to that shape.

Written November 19, 2026 · Tested with Go 1.26.4 · 17 min read

By the end of this guide
  • The first error: no go.mod file at all
  • The missing package: an import with no requirement
  • A misspelled standard package: a different message
  • An import cycle: two local packages that import each other

What this guide is

no required module provides package is the build saying it knows the package name you imported and cannot find a module that supplies it. In the setups in this guide, a package can come from three places: the standard library, the module you are standing in (the main module), and a module listed in your go.mod file. The error names the first shape: the package is in none of those three, and no requirement in go.mod covers it. The message even prints the command that would add one:

Output
main.go:6:2: no required module provides package github.com/example/greet; to add it:
    go get github.com/example/greet

The position, line 6 column 2, is the start of the import line. The package path in the message is the import path exactly as written in the source file, so a typo in the import and a genuinely missing dependency print the same family of message with different paths — the path itself is the first thing to read.

The examples here use Go 1.26.4. Every example starts from an empty directory with one module, created once:

Terminal
$ mkdir demo
$ cd demo
$ go mod init example.com/demo
go: creating new go.mod: module example.com/demo

Each program that follows replaces the contents of the files in that directory — start each one in a fresh directory, because a nested go.mod left over from an earlier program would exclude that directory from the module. When a build fails, the compiler prints the error to standard error and exits with status 1; when a program runs, its output is shown exactly as printed.

The first error: no go.mod file at all

Before any package can be missing, the module itself can be missing. In a directory with no go.mod file in it or in any parent directory, the build stops before it looks at a single import:

Terminal
$ go build .
go: go.mod file not found in current directory or any parent directory; see 'go help modules'

The fix is the command the setup block already ran: go mod init example.com/demo in the directory that holds the code. One variation is worth knowing, because it looks like a different error: inside a directory that sits under a Git repository, the same command instead prints go: cannot find main module, but found .git/config in ... followed by a suggestion to run go mod init (from the directory holding .git if it is above you). Both messages mean the same thing — there is no module here — and both are fixed by creating one. The module name is the path other code will use to import this module's packages, so pick the path the code will actually be imported under.

The missing package: an import with no requirement

The central shape of this guide imports a package from a module that go.mod does not require. The program is short:

Go
// main.go
package main

import (
    "fmt"

    "github.com/example/greet"
)

func main() {
    fmt.Println(greet.Hello())
}
Terminal
$ go build .
main.go:6:2: no required module provides package github.com/example/greet; to add it:
    go get github.com/example/greet

The build fails at the import, not at the call to greet.Hello(). Nothing in the program is wrong except the missing requirement: the import path is well formed, the package name is used correctly, and the function call matches the package's shape. The compiler never gets far enough to check any of that, because resolving the import comes first. That ordering is what makes this error easy to misread as a problem in the code — the code is fine, the module graph is short one requirement.

The fix the message suggests is go get github.com/example/greet, which downloads the module, records it as a requirement in go.mod, and records its checksum in go.sum. The sibling command go mod tidy does the same work from the other direction: it scans the imports in the module, finds modules that provide the missing packages, and updates go.mod and go.sum to match. For a package that really exists on the module proxy, either command closes the gap, and the next build succeeds. The package used in this guide, github.com/example/greet, does not exist, so neither command can download it here — that is exactly why the guide proves the fix with a local module instead, in the fixed-program section below. A go get for a package that does not exist fails at the lookup, not at the build, and the failure names the lookup: with the proxy switched off it reads module lookup disabled by GOPROXY=off, which is the subject of its own section below.

A misspelled standard package: a different message

Not every import that cannot be resolved prints no required module provides package. A misspelling of a standard package prints its own message, because a path with no dot in its first element is treated as a standard-library path rather than a module path:

Go
// main.go
package main

import "fmtx"

func main() {
    fmtx.Println("hi")
}
Terminal
$ go build .
main.go:3:8: package fmtx is not in std (/home/hatch/.local/go-sdk/src/fmtx)

The message says package fmtx is not in std, and the path in parentheses is the directory where the compiler looked — your Go installation's src directory, so the path on your machine will differ from the one printed here. The position, line 3 column 8, is the import string itself rather than the start of the line, because the failing thing is the path, not the statement. The fix is a spelling fix, not a module fix: fmtx is not a package, fmt is, and no go get or go mod tidy can supply a standard package that does not exist. When the message says is not in std, check the spelling against the standard library first; when it says no required module provides package, check the module graph first. The two messages divide the work that way.

An import cycle: two local packages that import each other

A third shape never mentions a missing package at all, and it is easy to chase as one. Two packages inside the same module import each other, and the build refuses the whole module:

Go
// main.go
package main

import "example.com/demo/a"

func main() { a.Say() }
Go
// a/a.go
package a

import (
    "fmt"

    "example.com/demo/b"
)

func Say() { fmt.Println(b.Word()) }
Go
// b/b.go
package b

import "example.com/demo/a"

func Word() string { return a.Tag }
Go
// a/tag.go
package a

const Tag = "hi"
Terminal
$ go build .
package example.com/demo
    imports example.com/demo/a from main.go
    imports example.com/demo/b from a.go
    imports example.com/demo/a from b.go: import cycle not allowed

The message lists the whole chain, one import per line, and ends with import cycle not allowed. The chain is the diagnosis: main imports a, a imports b, and b imports a again, so there is no order in which the packages can be compiled — each one needs the other first. The fix is to break the chain, not to add a requirement: here the shared constant Tag is the only thing b needs from a, so moving it into b removes the backward edge. Delete a/tag.go as well, so the constant lives in only one place — leaving the old copy would still compile, since the two Tag constants sit in different packages, but it would leave a stale copy behind. With Tag defined in b and a importing b alone, the same program runs and prints hi:

Go
// b/b.go
package b

const Tag = "hi"

func Word() string { return Tag }
Terminal
$ go run .
hi

The general rule behind the fix is that the shared thing moves down, not up: whichever package both sides need goes into the lower package, or into a third package both can import, so the arrows point one way. Adding a require line or running go mod tidy cannot help here, because the packages are already in the module — the graph is not missing an edge, it has one too many.

A lookup switched off: GOPROXY=off

The last failure shape is environmental. With the module proxy switched off, the build cannot even ask whether the missing package exists:

Terminal
$ GOPROXY=off go get github.com/example/greet
go: github.com/example/greet: module lookup disabled by GOPROXY=off
Terminal
$ GOPROXY=off go mod tidy
go: finding module for package github.com/example/greet
go: example.com/demo imports
    github.com/example/greet: cannot find module providing package github.com/example/greet: module lookup disabled by GOPROXY=off

go mod tidy prints two extra lines before the failure: it names the package it was looking for, then names the importing module and repeats the reason. The message to read is the last line, cannot find module providing package ... : module lookup disabled by GOPROXY=off — the lookup was disabled, so the package could not be found, which is a different fact from the package not existing. The build itself prints the no required module provides package form whether the proxy is on or off, because the build performs no lookup — it only reports that no requirement covers the import. Only go get and go mod tidy attempt a lookup, so only they print the module lookup disabled by GOPROXY=off form. The fix for the switched-off form is to turn the lookup back on: unset GOPROXY, or set it to the proxy the project uses, and run go mod tidy again — for a package that exists on the proxy. If the machine genuinely has no network, the local-module fix in the next section is the one that works offline, because it never consults a proxy at all.

The contrast that needs no requirement: a package in the main module

Before the fix, the contrast that separates a module problem from an import problem: a package inside the main module needs no requirement, no proxy, and no go get. The program below imports example.com/demo/greet, a package that lives in a greet directory under the module root, and it runs on the first try:

Go
// main.go
package main

import (
    "fmt"

    "example.com/demo/greet"
)

func main() {
    fmt.Println(greet.Hello())
}
Go
// greet/greet.go
package greet

func Hello() string { return "hello from the main module" }
Terminal
$ go run .
hello from the main module

The import path starts with the module path, example.com/demo, and the rest is the directory under the module root. That prefix is the test: if the import path starts with your own module path, the package is yours and the build finds it in the tree. If it starts with anything else, the build looks for a module that provides it, and a missing requirement is the error this guide is about. The mistake this contrast catches is treating a local package as an external dependency — adding a require line for your own module path, or a replace directive pointing at your own tree, when the package was already reachable as a subdirectory.

The fixed program: a local module behind a replace directive

The fix that works offline, and the one that proves the missing-package error is about the module graph rather than the code, is a replace directive pointing the import at a local module. The setup is a second module in a greet directory next to main.go:

Output
// greet/go.mod
module github.com/example/greet

go 1.26
Go
// greet/greet.go
package greet

func Hello() string { return "hello from the local module" }

The main module is the same program as the missing-package case, and the only change is in go.mod:

Terminal
$ go mod edit -replace github.com/example/greet=./greet
$ go mod tidy
go: found github.com/example/greet in github.com/example/greet v0.0.0-00010101000000-000000000000
$ go run .
hello from the local module

go mod tidy reports what it found, and the version it records is the placeholder v0.0.0-00010101000000-000000000000 — a local module has no published version, so the toolchain invents one. The resulting go.mod shows the whole fix in four lines:

Output
module example.com/demo

go 1.26.4

replace github.com/example/greet => ./greet

require github.com/example/greet v0.0.0-00010101000000-000000000000

The replace line says where the module lives on disk; the require line says which version the build wants. A replace directive is a development-time stand-in: it is the right fix while the dependency is local and unpublished, and the step that retires it is publishing the module and deleting the directive, after which go get records a real version. The program itself never changed between the failing build and the passing run — the same main.go that printed no required module provides package now prints hello from the local module, because the only thing that changed was the module graph.

The exact rule: where an import can resolve

An import path, in the setups in this guide, resolves in three places: the standard library, the main module, and the modules go.mod requires. Vendor directories and workspaces (go.work) can add further resolution sources; they are outside this guide. The main module is the module containing the directory where the go command is invoked, and its packages are the directories under that module's root whose paths start with the module path. A requirement in go.mod names a module and a version; the toolchain fetches that version from the proxy named by GOPROXY, or from the directory a replace directive names, and the packages inside it become importable. go mod tidy scans the module's imports, finds modules that provide the missing packages, and updates go.mod and go.sum to match; go get adds one named module at a time.

Against that rule, each error in this guide is one failed check: no go.mod file means there is no main module to stand in, so nothing resolves; no required module provides package means the path is in none of the three places; package fmtx is not in std means the path failed the first check and was never a standard package; import cycle not allowed means the packages are all present but cannot be ordered; module lookup disabled by GOPROXY=off means the third check never ran. The fix always restores the check that failed: create the module, add the requirement, correct the spelling, break the cycle, or re-enable the lookup.

The fixes, ranked

  • First, read the package path in the message. If it starts with your module path, the package is local — check the directory spelling and the package name before touching go.mod.
  • Second, read the message family. is not in std is a spelling fix; import cycle not allowed is a restructuring fix; module lookup disabled is an environment fix. Only no required module provides package is a requirement fix.
  • Third, for a requirement fix on a package that exists, run go mod tidy and build again. For a package that does not exist yet, or that you are developing alongside the main module, point a replace directive at the local directory and run go mod tidy, then delete the directive when the module is published.
  • Fourth, when the build still fails after the requirement is added, run go mod tidy again and read its output: it names the package it was looking for and the module that imports it, which separates a genuinely missing module from a misspelled import path.

Which fix for which cause

Cause Message Fix
No go.mod file go.mod file not found in current directory or any parent directory go mod init in the code directory
Import with no requirement no required module provides package ...; to add it: go get ... go mod tidy, or go get for the named module
Misspelled standard package package fmtx is not in std (...) Correct the spelling; no module command helps
Import cycle import cycle not allowed Move the shared code so the arrows point one way
Lookup switched off module lookup disabled by GOPROXY=off Re-enable the proxy, or use a local module with replace
Package in the main module None — it builds Nothing to fix; the import path starts with the module path

Checklist

  • Read the package path first: a path starting with your module path is a local package, and the build finds it in the tree without any requirement.
  • Read the message family before reaching for a command: is not in std means spelling, import cycle not allowed means structure, module lookup disabled means environment, and only no required module provides package means a missing requirement.
  • Check whether a go.mod file exists in the current directory or above it before diagnosing an import: without a main module, every import fails the same way.
  • Run go mod tidy after adding or changing an import, and read its output when it fails — it names the package it was looking for and the module that imports it.
  • Keep a replace directive as a development stand-in only: it points at a local directory, records a placeholder version, and should be deleted when the module is published and go get can record a real one.
  • Check GOPROXY when a lookup fails without naming a missing module: off disables the lookup entirely, and the error says so rather than saying the package does not exist.

Sources

  • Go Modules Reference — for the main module (the module containing the directory where the go command is invoked), for go mod tidy (it attempts to find new modules providing missing packages and to update go.mod and go.sum), for GOPROXY (a comma-separated list of proxy URLs or the keywords direct or off), and for the replace directive (when a module path appears in a require directive and is not replaced, the go command may need to download modules with that path), and for packages inside a module (each package within a module is a collection of source files in the same directory that are compiled together).
  • The Go Programming Language Specification — for the package clause (each source file consists of a package clause defining the package to which it belongs, followed by import declarations) and for import declarations (an import declaration states that the source file depends on functionality of the imported package).

Keep Exploring