golang/go · error

file URL missing drive letter

Error message

file URL missing drive letter

What it means

Windows-specific (url_windows.go): after the host check passes, the function inspects path[1:] (the part after the leading slash) expecting a drive letter volume (like C:). If filepath.VolumeName returns empty or a UNC prefix ("\\"), the URL has no valid Windows drive and cannot be turned into a local path. This is the path-level equivalent of "not a Windows absolute path."

Source

Thrown at src/cmd/go/internal/web/url_windows.go:40

	// The host part of a file URL (if any) is the UNC volume name,
	// but RFC 8089 reserves the authority "localhost" for the local machine.
	if host != "" && host != "localhost" {
		// A common "legacy" format omits the leading slash before a drive letter,
		// encoding the drive letter as the host instead of part of the path.
		// (See https://blogs.msdn.microsoft.com/freeassociations/2005/05/19/the-bizarre-and-unhappy-story-of-file-urls/.)
		// We do not support that format, but we should at least emit a more
		// helpful error message for it.
		if filepath.VolumeName(host) != "" {
			return "", errors.New("file URL encodes volume in host field: too few slashes?")
		}
		return `\\` + host + path, nil
	}

	// If host is empty, path must contain an initial slash followed by a
	// drive letter and path. Remove the slash and verify that the path is valid.
	if vol := filepath.VolumeName(path[1:]); vol == "" || strings.HasPrefix(vol, `\\`) {
		return "", errors.New("file URL missing drive letter")
	}
	return path[1:], nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. On Windows, supply a drive-qualified path: file:///C:/Users/me/x.
2. Use web.URLFromFilePath(absPath) on a Windows absolute path; it emits the correct drive-bearing URL.
3. For network shares, use the UNC form file://host/share/... so the host branch handles it (errors 142/143 do not fire).
4. OS-gate your config: emit drive-qualified URLs only when runtime.GOOS == "windows".

Example fix

// before (on Windows)
u, _ := url.Parse("file:///Users/me/app")
_, err := web.URLToFilePath(u) // -> "missing drive letter"

// after
u, _ := url.Parse("file:///C:/Users/me/app")
_, err := web.URLToFilePath(u)

// On Windows, require a drive-qualified path
if runtime.GOOS == "windows" {
    rel := strings.TrimPrefix(u.Path, "/")
    if filepath.VolumeName(rel) == "" {
        return errors.New("file URL path lacks a Windows drive letter")
    }
}

func hasWindowsDrive(u *url.URL) bool {
    p := strings.TrimPrefix(u.Path, "/")
    return filepath.VolumeName(p) != "" && !strings.HasPrefix(filepath.VolumeName(p), `\\`)
}

When it happens

Trigger: On Windows, passing a file: URL whose path is Unix-style (file:///home/me/x — no drive letter). Passing file://localhost/path where path lacks a drive. A file URL whose path is /share/dir interpreted as UNC but malformed.

Common situations: Cross-platform config files using Unix-style absolute paths on a Windows builder. CI matrices that share GOPATH/GOMODCACHE URLs across OSes without drive-letter translation. Mis-templated URL strings that omit the drive letter placeholder.

Related errors

• file URL encodes volume in host field: too few slashes?
• non-file URL
• file URL missing path
• file URL specifies non-local host
• path is not absolute

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