What causes "create capture session: %w" in netbirdio/netbird?

Set CaptureOptions.TextOutput to any io.Writer (even io.Discard during tests) or set Output for pcap capture

create capture session: %w

Error message

create capture session: %w

What it means

After filter parsing, StartCapture calls capture.NewSession, which requires at least one output sink: CaptureOptions.Output (an io.Writer receiving pcap bytes) or CaptureOptions.TextOutput (an io.Writer receiving human-readable packet lines). With neither set, NewSession fails with "at least one output sink required", which is what this wrapper reports. The session also derives snap length and buffer size from defaults when unset, so those cannot cause this error.

Source

Thrown at client/embed/embed.go:577

	var matcher capture.Matcher
	if opts.Filter != "" {
		m, err := capture.ParseFilter(opts.Filter)
		if err != nil {
			return nil, fmt.Errorf("parse filter: %w", err)
		}
		matcher = m
	}

	sess, err := capture.NewSession(capture.Options{
		Output:     opts.Output,
		TextOutput: opts.TextOutput,
		Matcher:    matcher,
		Verbose:    opts.Verbose,
		ASCII:      opts.ASCII,
	})
	if err != nil {
		return nil, fmt.Errorf("create capture session: %w", err)
	}

	if err := engine.SetCapture(sess); err != nil {
		sess.Stop()
		return nil, fmt.Errorf("set capture: %w", err)
	}

	return &CaptureSession{sess: sess, engine: engine}, nil
}

// StopCapture stops the active capture session if one is running.
func (c *Client) StopCapture() error {
	engine, err := c.getEngine()
	if err != nil {
		return err
	}
	return engine.SetCapture(nil)
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Set CaptureOptions.TextOutput to any io.Writer (even io.Discard during tests) or set Output for pcap capture
Validate the options struct before calling StartCapture so callers get a domain-specific error

Example fix

// before
sess, err := client.StartCapture(netbird.CaptureOptions{Filter: filter, Verbose: true})

// after
var buf bytes.Buffer
sess, err := client.StartCapture(netbird.CaptureOptions{Filter: filter, Verbose: true, TextOutput: &buf})

Defensive patterns

Strategy: validation

Validate before calling

func validCaptureOpts(o netbird.CaptureOptions) error {
    if o.Output == nil && o.TextOutput == nil {
        return errors.New("capture requires Output or TextOutput")
    }
    return nil
}

Try / catch

sess, err := client.StartCapture(opts)
if err != nil {
    if strings.Contains(err.Error(), "create capture session") {
        // programmer error in options; fix caller, no retry
    }
}

Prevention

Always set TextOutput (io.Discard in tests) when capturing
Wrap capture setup in your own helper that enforces the sink requirement once

When it happens

Trigger: StartCapture(CaptureOptions{Filter: "tcp", Verbose: true}) where both Output and TextOutput are nil. Typical when a caller only wants Stats() afterwards, or when a UI forwards verbose/ascii flags but forgets to wire the writer.

Common situations: Embedding the client and intending to poll CaptureStats without capturing output; refactoring that drops the writer argument; passing a writer via a custom struct field the API does not read.

Related errors

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