ginuerzh/gost · error

tap is not supported on darwin

Error message

tap is not supported on darwin

What it means

On macOS (darwin), createTap is a stub that unconditionally returns 'tap is not supported on darwin'. The library does not implement TAP device creation on macOS, so any attempt to start a TAP-mode interface there fails immediately at setup.

Source

Thrown at tuntap_darwin.go:62

	if err = addTunRoutes(ifce.Name(), cfg.Routes...); err != nil {
		return
	}

	itf, err = net.InterfaceByName(ifce.Name())
	if err != nil {
		return
	}

	conn = &tunTapConn{
		ifce: ifce,
		addr: &net.IPAddr{IP: ip},
	}
	return
}

func createTap(cfg TapConfig) (conn net.Conn, itf *net.Interface, err error) {
	err = errors.New("tap is not supported on darwin")
	return
}

func addTunRoutes(ifName string, routes ...IPRoute) error {
	for _, route := range routes {
		if route.Dest == nil {
			continue
		}
		cmd := fmt.Sprintf("route add -net %s -interface %s", route.Dest.String(), ifName)
		log.Log("[tun]", cmd)
		args := strings.Split(cmd, " ")
		if er := exec.Command(args[0], args[1:]...).Run(); er != nil {
			return fmt.Errorf("%s: %v", cmd, er)
		}
	}
	return nil
}

View on GitHub (pinned to a33fdbf4c9)

Solutions

  1. Use TUN mode instead of TAP on macOS (the library supports tun on darwin).
  2. Run the TAP endpoint on a Linux host; keep the macOS machine as a TUN client.
  3. Guard the config at startup: check runtime.GOOS == "darwin" before enabling TAP and fall back to TUN or fail with a clear message.

Example fix

// before
listener, err := TapListener(...) // darwin -> 'tap is not supported on darwin'
// after
if runtime.GOOS == "darwin" {
    // use TUN instead
    listener, err = TunListener(...)
} else {
    listener, err = TapListener(...)
}
Defensive patterns

Strategy: fallback

Validate before calling

if runtime.GOOS == "darwin" && mode == "tap" {
    return errors.New("tap is unsupported on darwin; use tun mode")
}

Type guard

func tapSupported() bool {
    return runtime.GOOS != "darwin"
}

Try / catch

conn, itf, err := createTap(cfg)
if err != nil {
    if runtime.GOOS == "darwin" {
        conn, itf, err = createTun(cfg.ToTunConfig()) // fall back to TUN
    }
    if err != nil { return err }
}

Prevention

When it happens

Trigger: Starting a TAP (ethernet) tunnel on macOS via createTap(TapConfig) — e.g. running a gost TAP route with -L 'tap://...' on darwin.

Common situations: Developing/testing VPN-style taps on a Mac; copying a Linux TAP config to macOS; CI on darwin runners exercising TAP features.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of ginuerzh/gost@a33fdbf4c9 (2026-09-02). Data as JSON: /api/errors/3cfff34e1fc6e8fb. Report an issue: GitHub.