What causes "failed to create namespace: %v" in hashicorp/nomad?

Read the wrapped cause and fix accordingly (usually CAP_SYS_ADMIN or mount propagation)

failed to create namespace: %v

Error message

failed to create namespace: %v

What it means

This is the top-level failure reported by NewNS when any step inside the per-thread creation goroutine (get current ns, unshare, bind mount) failed. It wraps the inner error, so the root cause (permissions, mount failure) is in the wrapped message. Receiving it means no usable network namespace was created.

Source

Thrown at client/lib/nsutil/netns_linux.go:125

			err = fmt.Errorf("error from unshare: %v", err)
			return
		}

		// Put this thread back to the orig ns, since it might get reused (pre go1.10)
		defer origNS.Set()

		// bind mount the netns from the current thread (from /proc) onto the
		// mount point. This causes the namespace to persist, even when there
		// are no threads in the ns.
		err = unix.Mount(getCurrentThreadNetNSPath(), nsPath, "none", unix.MS_BIND, "")
		if err != nil {
			err = fmt.Errorf("failed to bind mount ns at %s: %v", nsPath, err)
		}
	})()
	wg.Wait()

	if err != nil {
		return nil, fmt.Errorf("failed to create namespace: %v", err)
	}

	return GetNS(nsPath)
}

// UnmountNS unmounts the NS held by the netns object
func UnmountNS(nsPath string) error {
	// Only unmount if it's been bind-mounted (don't touch namespaces in /proc...)
	if strings.HasPrefix(nsPath, NetNSRunDir) {
		if err := unix.Unmount(nsPath, unix.MNT_DETACH); err != nil {
			return fmt.Errorf("failed to unmount NS: at %s: %w", nsPath, err)
		}

		if err := os.Remove(nsPath); err != nil {
			return fmt.Errorf("failed to remove ns path %s: %w", nsPath, err)
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Read the wrapped cause and fix accordingly (usually CAP_SYS_ADMIN or mount propagation)
Run with sufficient privileges: sudo, --privileged, or --cap-add SYS_ADMIN
Pre-configure /run/netns as a shared bind mount on the host
Validate with 'unshare -n true' that the environment supports netns creation at all

Example fix

// before
ns, err := nsutil.NewNS() // failed to create namespace: error from unshare: operation not permitted
// after: run the binary with the needed capability
// setcap cap_sys_admin+ep /usr/local/bin/mybin
ns, err := nsutil.NewNS()

Defensive patterns

Strategy: try-catch

Validate before calling

if err := exec.Command("unshare", "-n", "true").Run(); err != nil {
    return fmt.Errorf("netns creation unsupported in this environment: %v", err)
}

Try / catch

ns, err := nsutil.NewNS()
var nsErr *netnsError
if err != nil {
    if strings.Contains(err.Error(), "failed to create namespace") {
        log.Fatalf("netns unavailable: %v (run with CAP_SYS_ADMIN and shared /run/netns)", err)
    }
    return err
}

Prevention

Fail fast with an environment capability check at startup
Standardize privileged requirements in deployment manifests (capabilities: SYS_ADMIN)
Keep /run/netns shared-mount setup in infrastructure-as-code
Pin runtime/kernel versions known to support netns in your CI matrix

When it happens

Trigger: NewNS (via CreateNetwork) returns this whenever the inner err from the goroutine is non-nil — most commonly unshare EPERM or bind-mount failure of the new ns onto /var/run/netns/<name>.

Common situations: Running tests as unprivileged user on CI; containers missing SYS_ADMIN; environments where /run is read-only or not shared; Kernel without NET_NS support.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/5612ab5d74cd2e80. Report an issue: GitHub.