error reading %s: missing module declaration. To specify the

Error message

error reading %s: missing module declaration. To specify the module path:
	go mod edit -module=example.com/mod

What it means

Returned by modload.ReadModFile when the parsed go.mod has no 'module' directive at all. The go.mod file is structurally parseable but is missing the mandatory module path declaration, so the toolchain cannot identify the module.

Source

Thrown at src/cmd/go/internal/modload/modfile.go:70

					toolchain = f.Toolchain.Name
				}
				return nil, nil, &gover.TooNewError{What: base.ShortPath(gomod), GoVersion: f.Go.Version, Toolchain: toolchain}
			}
		}

		// Errors returned by modfile.Parse begin with file:line.
		return nil, nil, fmt.Errorf("errors parsing %s:\n%w", base.ShortPath(gomod), shortPathErrorList(err))
	}
	if f.Go != nil && gover.Compare(f.Go.Version, gover.Local()) > 0 {
		toolchain := ""
		if f.Toolchain != nil {
			toolchain = f.Toolchain.Name
		}
		return nil, nil, &gover.TooNewError{What: base.ShortPath(gomod), GoVersion: f.Go.Version, Toolchain: toolchain}
	}
	if f.Module == nil {
		// No module declaration. Must add module path.
		return nil, nil, fmt.Errorf("error reading %s: missing module declaration. To specify the module path:\n\tgo mod edit -module=example.com/mod", base.ShortPath(gomod))
	} else if err := CheckReservedModulePath(f.Module.Mod.Path); err != nil {
		return nil, nil, fmt.Errorf("error reading %s: invalid module path: %q", base.ShortPath(gomod), f.Module.Mod.Path)
	}

	return data, f, err
}

func shortPathErrorList(err error) error {
	if el, ok := errors.AsType[modfile.ErrorList](err); ok {
		for i := range el {
			el[i].Filename = base.ShortPath(el[i].Filename)
		}
	}
	return err
}

// A modFileIndex is an index of data corresponding to a modFile
// at a specific point in time.

View on GitHub (pinned to b6b368adc5)

Solutions

Run 'go mod edit -module=example.com/yourmod' to add the module declaration.
Or 'go mod init example.com/yourmod' if go.mod itself does not yet exist or should be reinitialized.
Verify the module path follows the rules (domain/path, no spaces).

Example fix

// before (go.mod)
go 1.21

require example.com/pkg v1.0.0
// error: missing module declaration

// after
module example.com/yourmod

go 1.21

require example.com/pkg v1.0.0

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a module directive exists:
//   grep -q '^module ' go.mod || echo "missing module directive"
// Or programmatically: f, _ := modfile.Parse("go.mod", data, nil); if f.Module == nil { /* reinit */ }

Type guard

func hasModuleDirective(data []byte) bool {
    f, err := modfile.ParseLax("go.mod", data, nil)
    return err == nil && f.Module != nil
}

Prevention

Always start a new module with 'go mod init <path>'.
Include a go.mod presence check in project scaffolding templates.
Lint go.mod in CI with 'go mod edit -print >/dev/null'.

When it happens

Trigger: Any 'go' command reading a go.mod that lacks a 'module <path>' line — typically a freshly created or accidentally truncated go.mod.

Common situations: Running 'go mod init' was skipped; the module line was deleted during editing; a go.mod was created by hand without the module directive; a template/generated file omitted it.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/407e895b815fa785. Report an issue: GitHub.