netbirdio/netbird · error

setenv: %w

Error message

setenv: %w

What it means

Returned by embed.New when os.Setenv for the netstack mode flag (netstack.EnvUseNetstackMode, i.e. the environment variable that switches the agent into netstack mode) fails while enabling userspace networking (opts.NoUserspace == false). os.Setenv on fixed keys virtually never fails; on Unix it can only fail on an invalid key or allocation failure.

Source

Thrown at client/embed/embed.go:175

			return nil, fmt.Errorf("invalid MTU: %w", err)
		}
	}

	if opts.LogOutput != nil {
		logrus.SetOutput(opts.LogOutput)
	}

	if opts.LogLevel != "" {
		level, err := logrus.ParseLevel(opts.LogLevel)
		if err != nil {
			return nil, fmt.Errorf("parse log level: %w", err)
		}
		logrus.SetLevel(level)
	}

	if !opts.NoUserspace {
		if err := os.Setenv(netstack.EnvUseNetstackMode, "true"); err != nil {
			return nil, fmt.Errorf("setenv: %w", err)
		}
		if err := os.Setenv(netstack.EnvSkipProxy, "true"); err != nil {
			return nil, fmt.Errorf("setenv: %w", err)
		}
	}

	if opts.StatePath != "" {
		// TODO: Disable state if path not provided
		if err := os.Setenv("NB_DNS_STATE_FILE", opts.StatePath); err != nil {
			return nil, fmt.Errorf("setenv: %w", err)
		}
	}

	var err error
	var parsedLabels domain.List
	if parsedLabels, err = domain.FromStringList(opts.DNSLabels); err != nil {
		return nil, fmt.Errorf("invalid dns labels: %w", err)
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Treat it as a fatal environment/runtime problem: check process memory limits and restart the embedding process.
2. If it recurs on a specific platform, report it upstream; there is no caller-side configuration that fixes a failing os.Setenv.

client, err := embed.New(opts)
if err != nil {
    if strings.HasPrefix(err.Error(), "setenv") {
        // environment/runtime level failure: restart the process rather than retry in-process
        log.Fatalf("runtime cannot set env: %v", err)
    }
    return err
}

When it happens

Trigger: Any embed.New call without NoUserspace=true on a platform or process state where setting an environment variable fails (extreme memory pressure, or a Go runtime/OS combination refusing setenv).

Common situations: Almost never observed in practice; when it appears it signals the process is out of memory or the runtime is in a degraded state rather than a configuration mistake.

Related errors

• get current user: %v
• get active profile file path: %v
• get current user: %v
• get current user: %w
• invalid MTU: %w

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/aaa2f10020002717. Report an issue: GitHub.