netbirdio/netbird · error

%s

Error message

%s

What it means

handleCaptureError converts a gRPC status error coming from the StartCapture RPC or the packet stream into a plain message string, discarding the gRPC envelope (code, rpc name). This is the shape you see when the daemon itself refuses or aborts the capture: capture not enabled at service install time, the capture device unavailable (kernel WireGuard mode, interface not connected), or the stream failing mid-capture. The concrete reason is whatever message the daemon attached to the status.

Source

Thrown at client/cmd/capture.go:193

		fi, statErr := os.Stat(tmpPath)
		if statErr != nil || fi.Size() == 0 {
			if rmErr := os.Remove(tmpPath); rmErr != nil && !os.IsNotExist(rmErr) {
				merr = multierror.Append(merr, fmt.Errorf("remove empty output file: %w", rmErr))
			}
			return nberrors.FormatErrorOrNil(merr)
		}
		if err := os.Rename(tmpPath, outPath); err != nil {
			merr = multierror.Append(merr, fmt.Errorf("rename output file: %w", err))
			return nberrors.FormatErrorOrNil(merr)
		}
		cmd.PrintErrf("Wrote %s\n", outPath)
		return nberrors.FormatErrorOrNil(merr)
	}, nil
}

func handleCaptureError(err error) error {
	if s, ok := status.FromError(err); ok {
		return fmt.Errorf("%s", s.Message())
	}
	return err
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. For the 'not enabled' refusal: reconfigure the service with capture enabled (netbird up --enable-capture or reconfigure-time flag per your install) and retry
2. Ensure the agent is connected (netbird status) and running in a capture-capable mode (userspace/netstack), then retry
3. Check daemon logs (journalctl -u netbird or the log file) at the timestamp — the same status message appears with more context there
4. Restart the daemon if the stream broke due to a daemon restart, then rerun the capture

Example fix

# before: capture requested on an install without it
netbird debug capture
# -> capture is not enabled ...

# after: enable at (re)configure time, then capture
netbird up --enable-capture
netbird debug capture -d 30s -o /tmp/c.pcap

// Before capturing, confirm the feature is on and the peer is connected:
out, _ := exec.Command("netbird", "status").Output() // check 'Connected' and capture support
// At install time: netbird up --enable-capture

// Distinguish daemon refusals from transport failures:
func isCaptureDisabled(err error) bool {
    s, ok := status.FromError(err)
    return ok && strings.Contains(s.Message(), "not enabled")
}

// Map known daemon refusals to actionable guidance:
err := runCapture()
if s, ok := status.FromError(err); ok {
    switch {
    case strings.Contains(s.Message(), "not enabled"):
        hint("re-run netbird up --enable-capture")
    case strings.Contains(s.Message(), "unavailable"):
        hint("check kernel/userspace mode and connection")
    default:
        hint("inspect daemon logs: " + s.Message())
    }
}

When it happens

Trigger: Running netbird debug capture without --enable-capture set at install/reconfigure time (daemon rejects); agent in kernel-mode WireGuard where no userspace capture hook exists; peer not connected so the capture device is absent; daemon restarting/context canceled mid-stream surfacing as 'context canceled' or 'rpc error' text.

Common situations: Fresh install forgetting the enable flag; switching the agent between userspace and kernel modes; capture started while netbird is still connecting; version skew between CLI and daemon where StartCapture is unsupported.

Related errors

• %s: %w
• failed to get config: %v
• failed to set log level: %v
• wait for extend session: %v
• switch profile: %v

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