containerd/containerd · error

not implemented on unix

Error message

not implemented on unix

What it means

errNotImplementedOnUnix is the stub error returned by every NetNS constructor/operation in the non-Linux (netns_other.go) build of pkg/netns, because network namespaces are a Linux-only kernel feature. Any attempt to create, remove, or query a NetNS on a platform compiled against this file fails immediately with this error.

Source

Thrown at pkg/netns/netns_other.go:25

   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   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 netns

import (
	"errors"
)

var errNotImplementedOnUnix = errors.New("not implemented on unix")

// NetNS holds network namespace.
type NetNS struct {
	path string
}

// NewNetNS creates a network namespace.
func NewNetNS(baseDir string) (*NetNS, error) {
	return nil, errNotImplementedOnUnix
}

// NewNetNSFromPID returns the netns from pid or a new netns if pid is 0.
func NewNetNSFromPID(baseDir string, pid uint32) (*NetNS, error) {
	return nil, errNotImplementedOnUnix
}

// LoadNetNS loads existing network namespace.
func LoadNetNS(path string) *NetNS {

View on GitHub (pinned to 4246446a2b)

Solutions

1. Run the workload on Linux, where the real netns_linux.go implementation is compiled
2. On macOS, use a Linux VM or container (Docker for Mac, Lima, colima) for namespace-dependent features
3. Guard code with runtime.GOOS == "linux" and skip/replace NetNS-dependent paths elsewhere
4. If a stub is needed for tests, build against this stub deliberately and never call these functions

Example fix

// before
ns, err := netns.NewNetNS() // fails on darwin

// after
if runtime.GOOS != "linux" {
    return errors.New("network namespaces require Linux")
}
ns, err := netns.NewNetNS()

if runtime.GOOS != "linux" {
    // NetNS APIs are stubbed on non-Linux builds
    return errors.New("network namespaces require Linux")
}

When it happens

Trigger: Calling NewNetNS, NewNetNSFromPID, Remove, or Closed on a build targeting a non-Linux OS (e.g. darwin, freebsd) where netns_other.go is compiled in.

Common situations: Running containerd or a containerd-based tool on macOS for local development; unit tests built with GOOS=darwin or GOOS=windows; sandbox/Pods (e.g. Kubernetes CRI sandbox creation) attempted on unsupported hosts.

Related errors

• not implemented on windows
• failed to mount netns from pid %d: %w
• timeout creating new loopback device
• mount options is too long
• unprivileged_icmp and unprivileged_port require kernel versi

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/fafb08636c3df2af. Report an issue: GitHub.