file URL encodes volume in host field: too few slashes?

Error message

file URL encodes volume in host field: too few slashes?

What it means

Windows-specific (url_windows.go): convertFileURLPath detects that the host portion of a file: URL looks like a Windows drive letter (e.g. file://C:/path — only two slashes after file:). This is the well-known broken legacy format where the drive letter is encoded as the host. The go command refuses to support it and emits a hint pointing at the missing slash, because accepting it would silently mis-parse many URLs.

Source

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

	if len(path) == 0 || path[0] != '/' {
		return "", errNotAbsolute
	}

	path = filepath.FromSlash(path)

	// We interpret Windows file URLs per the description in
	// https://blogs.msdn.microsoft.com/ie/2006/12/06/file-uris-in-windows/.

	// 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

Use three slashes for local Windows paths: file:///C:/Users/me/x so the host is empty and the drive lives in Path.
Build Windows file URLs with web.URLFromFilePath(absPath) which always emits the correct form.
When interpolating, do "file:///" + filepath.ToSlash(path) — never "file://" + path.
Add a lint check that flags file://<single-letter>: patterns in config files.

Example fix

// before
u, _ := url.Parse("file://C:/Users/me/app")
_, err := web.URLToFilePath(u) // -> "encodes volume in host field"

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

Defensive patterns

Strategy: validation

Validate before calling

// reject the legacy two-slash drive-letter form on Windows
if runtime.GOOS == "windows" && u.Host != "" && u.Host != "localhost" &&
    filepath.VolumeName(u.Host) != "" {
    return errors.New("rewrite as file:///" + u.Host + u.Path)
}

Type guard

func isWellFormedWindowsFileURL(u *url.URL) bool {
    if u.Scheme != "file" { return false }
    if u.Host == "" || u.Host == "localhost" { return true }
    return filepath.VolumeName(u.Host) == ""
}

Prevention

Always emit three slashes for local Windows file URLs (file:///C:/...).
Use web.URLFromFilePath to construct Windows file URLs correctly.
Add a CI lint that flags file://[A-Za-z]: patterns.

When it happens

Trigger: On Windows, parsing "file://C:/Users/me/x" (two slashes) instead of "file:///C:/Users/me/x" (three slashes). Configuration files or build logs that emit file://C: URLs from naive join logic. URL builders that concatenate "file://" + drivePath without accounting for the leading slash.

Common situations: Copy-pasting Windows file URLs from browsers or emails that drop the third slash. Tools that produce URLs via "file://" + filepath.ToSlash(path) where path starts with "C:\". Documentation written by authors unfamiliar with the three-slash Windows convention.

Related errors

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