cilium/cilium · error

endpoint is required

Error message

endpoint is required

What it means

newStageCmd resolves the target endpoint before doing anything; it reads the `endpoint` flag and returns "endpoint is required" when the string is empty. The command cannot simulate a policy diff without knowing which endpoint's map to inspect.

Source

Thrown at pkg/policy/commands/mapstate_diff.go:202

	Deleted *entryOut `json:"deleted,omitempty"`
	Added   *entryOut `json:"added,omitempty"`
}

func newStageCmd(params CmdParams, state *script.State) (*stageCmd, error) {
	s := &stageCmd{
		params: params,
		log:    slog.New(slog.NewTextHandler(state.LogWriter(), nil)),
	}

	var err error
	s.toAddPaths, err = state.Flags.GetStringSlice("filename")
	if err != nil {
		return nil, err
	}

	epSpec, _ := state.Flags.GetString("endpoint")
	if epSpec == "" {
		return nil, fmt.Errorf("endpoint is required")
	}

	eps, _ := lookupEPs(params.EPL, []string{epSpec})
	if len(eps) != 1 {
		return nil, fmt.Errorf("endpoint not found!")
	}
	s.ep = eps[0]
	s.epID, err = s.ep.GetSecurityIdentity()
	if err != nil {
		return nil, err
	}

	pr := params.Repository.(*policy.Repository)
	if pr == nil {
		return nil, fmt.Errorf("BUG: could not cast policy repository")
	}
	// Take a snapshot of the repository so we can make changes
	s.pr, s.ids = pr.Snapshot(s.log,

View on GitHub (pinned to ac7b90affa)

Solutions

1. Pass `--endpoint <id|pod-name>` identifying the target endpoint
2. Fix the script variable so it expands to a real endpoint ID (`cilium endpoint list` to find IDs)
3. Quote/validate the flag value in wrappers before invoking the command

Example fix

// before
ENDPOINT="" ; cilium bpf policy mapstate-diff --endpoint $ENDPOINT ...
// after
ENDPOINT=$(cilium endpoint list -o json | jq -r '.[0].id') ; cilium bpf policy mapstate-diff --endpoint "$ENDPOINT" ...

epFlag := ""
if epFlag == "" {
    return errors.New("--endpoint must be set before invoking mapstate-diff")
}

if err := run(); err != nil {
    if strings.Contains(err.Error(), "endpoint is required") {
        fmt.Fprintln(os.Stderr, "pass --endpoint <id|namespace/pod>")
        os.Exit(2)
    }
    return err
}

When it happens

Trigger: Calling mapstate-diff without the `--endpoint` flag, or with `--endpoint ""` (empty interpolation in a script).

Common situations: Omitting the flag in automation, a shell variable expanding to empty (unset EP_ID), or copying examples that assume a default endpoint.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• service type %q is not valid
• invalid peer IP address: %w
• invalid clusterID: %w
• invalid endpoint id %s
• unsupported output format %s

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/6ead0d62902a9d6c. Report an issue: GitHub.