What causes "path is not absolute" in golang/go?

Use an absolute path in the file:// URL.

path is not absolute

Error message

path is not absolute

What it means

urlToFilePath converts a file:// URL to a filesystem path and requires the path to be absolute (errNotAbsolute). A relative path in a file URL is rejected because module fetching needs an unambiguous absolute location.

Source

Thrown at src/cmd/go/internal/web/url.go:17

// Copyright 2019 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package web

import (
	"errors"
	"net/url"
	"path/filepath"
	"strings"
)

// TODO(golang.org/issue/32456): If accepted, move these functions into the
// net/url package.

var errNotAbsolute = errors.New("path is not absolute")

func urlToFilePath(u *url.URL) (string, error) {
	if u.Scheme != "file" {
		return "", errors.New("non-file URL")
	}

	checkAbs := func(path string) (string, error) {
		if !filepath.IsAbs(path) {
			return "", errNotAbsolute
		}
		return path, nil
	}

	if u.Path == "" {
		if u.Host != "" || u.Opaque == "" {
			return "", errors.New("file URL missing path")
		}
		return checkAbs(filepath.FromSlash(u.Opaque))

View on GitHub (pinned to b6b368adc5)

Solutions

Use an absolute path in the file:// URL.
Prefer a plain filesystem path in a replace directive instead of a file:// URL.

Example fix

// before
// replace example.com/lib => file:./lib

// after
// replace example.com/lib => /home/me/proj/lib

Defensive patterns

Strategy: validation

Validate before calling

// Ensure file:// URLs point at absolute paths.
func absoluteFileURL(s string) error {
    u, err := url.Parse(s)
    if err != nil { return err }
    if u.Scheme == "file" && !filepath.IsAbs(u.Path) {
        return errors.New("file URL path must be absolute")
    }
    return nil
}

Type guard

null

Try / catch

null

Prevention

Use plain filesystem paths (not file:// URLs) in replace directives.
Resolve relative paths to absolute before constructing file:// URLs.

When it happens

Trigger: A file:// URL with a relative path (e.g. file:lib or file://./rel) is passed into module resolution.

Common situations: Misconstructed file:// URLs in replace directives or tooling that builds URLs from non-absolute paths.

Related errors

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