docker/compose · error

named pipes are only available on Windows

Error message

named pipes are only available on Windows

What it means

dialNamedPipe is a build-tag stub: on non-Windows builds (conn_unix.go) it unconditionally returns this error because named pipes are a Windows-only transport. It fires when Unix code paths attempt an npipe:// dial — i.e. memnet.Dial(ctx, "npipe", ...) on Linux/macOS. The npipe address is meaningless there, so the call fails fast instead of attempting a bogus dial.

Source

Thrown at internal/memnet/conn_unix.go:31

   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

package memnet

import (
	"context"
	"fmt"
	"net"
	"syscall"
)

const maxUnixSocketPathSize = len(syscall.RawSockaddrUnix{}.Path)

func dialNamedPipe(_ context.Context, _ string) (net.Conn, error) {
	return nil, fmt.Errorf("named pipes are only available on Windows")
}

func validateSocketPath(addr string) error {
	if len(addr) > maxUnixSocketPathSize {
		return fmt.Errorf("socket address is too long: %s", addr)
	}
	return nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. On Unix, use a Unix socket endpoint: DOCKER_HOST=unix:///var/run/docker.sock.
2. Branch on runtime.GOOS (or the endpoint scheme appropriate for the platform) before selecting npipe.
3. Stop sourcing Windows-specific env files in Linux containers/CI.
4. If you truly need the Windows pipe, run the dial from a Windows host or a Windows container.

Example fix

// before
conn, err := memnet.DialEndpoint(ctx, "npipe:////./pipe/docker_engine") // on Linux

// after
var endpoint string
if runtime.GOOS == "windows" {
    endpoint = "npipe:////./pipe/docker_engine"
} else {
    endpoint = "unix:///var/run/docker.sock"
}
conn, err := memnet.DialEndpoint(ctx, endpoint)

if strings.HasPrefix(ep, "npipe://") && runtime.GOOS != "windows" {
    return fmt.Errorf("npipe endpoint %q requires windows", ep)
}

func isWindowsPipeEndpoint(ep string) bool {
    return runtime.GOOS == "windows" && strings.HasPrefix(ep, "npipe://")
}

conn, err := memnet.DialEndpoint(ctx, ep)
if err != nil {
    if runtime.GOOS != "windows" && strings.HasPrefix(ep, "npipe://") {
        err = fmt.Errorf("wrong-platform DOCKER_HOST (npipe on %s); use unix:// socket: %w", runtime.GOOS, err)
    }
    return nil, err
}

When it happens

Trigger: Running on Linux/macOS and calling memnet.Dial or DialEndpoint with an npipe:// endpoint (e.g. DOCKER_HOST=npipe:////./pipe/docker_engine carried over from a Windows machine or CI matrix).

Common situations: Shared .env or CI configs written for Windows devs used on Linux runners; scripts copying DOCKER_HOST values between platforms; cross-platform tools that don't branch on runtime.GOOS before choosing the transport.

Related errors

• unsupported protocol for address: %s
• unsupported network: %s
• socket address is too long: %s
• making %q relative to %q: %w
• failed to pull OCI resource %q: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/bdda4737e3564d0d. Report an issue: GitHub.