golang/go · error

file URL specifies non-local host

Error message

file URL specifies non-local host

What it means

Thrown by convertFileURLPath on non-Windows (Plan 9, Unix, etc.) when a file: URL carries a host component that is neither empty nor "localhost". On Unix a file URL is local-only — an authority field names a remote machine, and the go command does not fetch files over the network by host. RFC 8089 allows file://localhost/ but treats any other host as remote and unsupported here.

Source

Thrown at src/cmd/go/internal/web/url_other.go:18

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

//go:build !windows

package web

import (
	"errors"
	"path/filepath"
)

func convertFileURLPath(host, path string) (string, error) {
	switch host {
	case "", "localhost":
	default:
		return "", errors.New("file URL specifies non-local host")
	}
	return filepath.FromSlash(path), nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Mount the remote share locally and reference it by absolute filesystem path (e.g. /mnt/share/...) instead of a file://host URL.
2. Strip the host: if the file is actually local, use file:///path (three slashes → empty host) or file://localhost/path.
3. Route remote file acquisition through a real download step (http(s) or ssh) and pass the local cached path to the go command.
4. In cross-platform tooling, branch on runtime.GOOS and only emit host-bearing file URLs on windows.

Example fix

// before (on Linux)
u, _ := url.Parse("file://fileserver/builds/m.zip")
p, err := web.URLToFilePath(u) // -> "non-local host"

// after
u, _ := url.Parse("file:///mnt/fileserver/builds/m.zip")
p, err := web.URLToFilePath(u)

if u.Host != "" && u.Host != "localhost" {
    return fmt.Errorf("file URL host %q is not local; mount the share and use a local path", u.Host)
}

func isLocalFileURL(u *url.URL) bool {
    return u.Scheme == "file" && (u.Host == "" || u.Host == "localhost")
}

When it happens

Trigger: Parsing "file://fileserver/share/x" or "file://192.168.1.5/data/y" on a Unix/Plan9 host. Manually setting u.Host to a machine name and then calling URLToFilePath. Reusing a Windows-style file://host/share URL on a Linux build machine without remapping.

Common situations: Cross-platform build scripts that hardcode file://UNC paths and are run on Linux/macOS CI. Misconfigured GOPATH/GOMODCACHE pointing at a network share via a file URL rather than a mounted path. Documentation copy-pasted from a Windows context into a Unix toolchain invocation.

Related errors

• non-file URL
• file URL missing path
• file URL encodes volume in host field: too few slashes?
• file URL missing drive letter
• could not parse URL %s: %v

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