cilium/cilium · error

unable to understand network config: %w

Error message

unable to understand network config: %w

What it means

The GenericVethChainer's Add step in the Cilium CNI chaining plugin first validates the previous plugin's result by calling cniVersion.ParsePrevResult on the chained NetConf. This error wraps the parse failure, meaning the CNI network configuration's prevResult field is missing or malformed for the plugin's CNI version.

Source

Thrown at plugins/cilium-cni/chaining/generic-veth/generic-veth.go:35

	"github.com/cilium/cilium/api/v1/models"
	"github.com/cilium/cilium/pkg/client"
	"github.com/cilium/cilium/pkg/datapath/link"
	"github.com/cilium/cilium/pkg/datapath/linux/safenetlink"
	endpointid "github.com/cilium/cilium/pkg/endpoint/id"
	"github.com/cilium/cilium/pkg/logging/logfields"
	"github.com/cilium/cilium/pkg/mac"
	"github.com/cilium/cilium/pkg/netns"
	chainingapi "github.com/cilium/cilium/plugins/cilium-cni/chaining/api"
	"github.com/cilium/cilium/plugins/cilium-cni/lib"
	"github.com/cilium/cilium/plugins/cilium-cni/types"
)

type GenericVethChainer struct{}

func (f *GenericVethChainer) Add(ctx context.Context, pluginCtx chainingapi.PluginContext, cli *client.Client) (res *cniTypesVer.Result, err error) {
	err = cniVersion.ParsePrevResult(&pluginCtx.NetConf.NetConf)
	if err != nil {
		err = fmt.Errorf("unable to understand network config: %w", err)
		return
	}

	var prevRes *cniTypesVer.Result
	prevRes, err = cniTypesVer.NewResultFromResult(pluginCtx.NetConf.PrevResult)
	if err != nil {
		err = fmt.Errorf("unable to get previous network result: %w", err)
		return
	}

	defer func() {
		if err != nil {
			pluginCtx.Logger.Error(
				"Unable to create endpoint",
				logfields.Error, err,
				logfields.Previous, pluginCtx.NetConf.PrevResult,
			)
		}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Fix the CNI chaining config so a prior plugin emits a result before generic-veth runs (correct plugin ordering in the list)
2. Validate the conflist JSON (e.g. with cnitool or a JSON schema check) for a well-formed prevResult
3. Ensure the cniVersion fields are consistent (0.3.1/0.4.0+) across chained plugins
4. Inspect the wrapped error to pinpoint whether prevResult is absent or unparseable

Example fix

// before
{"cniVersion":"0.3.1","name":"veth","plugins":[{"type":"cilium-cni"},{"type":"generic-veth"}]}
// after
{"cniVersion":"0.3.1","name":"veth","plugins":[{"type":"portmap",...},{"type":"cilium-cni"},{"type":"generic-veth"}]} // a producing plugin precedes generic-veth, so prevResult is populated

// validate the CNI config before invoking the plugin
var netConf struct {
    cniTypes.NetConf
}
if err := json.Unmarshal(configBytes, &netConf); err != nil {
    return fmt.Errorf("invalid CNI config: %w", err)
}
if netConf.PrevResult == nil && netConf.RawPrevResult == nil {
    return fmt.Errorf("prevResult missing: a prior plugin must run before generic-veth")
}

func hasValidPrevResult(netConf *chainingapi.PluginContext) bool {
    if netConf == nil || netConf.NetConf.PrevResult == nil {
        return false
    }
    return cniVersion.GreaterThanOrEqualTo(netConf.NetConf.CNIVersion, "0.3.0")
}

res, err := chainer.Add(ctx, pluginCtx, cli)
if err != nil && strings.Contains(err.Error(), "unable to understand network config") {
    // fail the CNI ADD clearly so kubelet surfaces the malformed config
    return nil, fmt.Errorf("chaining config invalid, check plugin ordering/prevResult: %w", err)
}

When it happens

Trigger: Invoking the generic-veth chaining plugin's Add when the input CNI config lacks a valid prevResult, has an unsupported/inconsistent cniVersion, or the prevResult does not match the declared version.

Common situations: Miswritten CNI conflist where the chaining plugin is ordered before a plugin that produces a result; hand-edited 10-cilium-cni.conf with missing prevResult; CNI spec version mismatches after upgrades.

Related errors

• certificate and private key are both required, but only one
• bpf-lb-dsr-dispatch ipip creates IPIP tunnels that aren't co
• BIG TCP in tunneling mode requires pending kernel support
• BIG TCP with bpf-lb-dsr-dispatch geneve requires pending ker
• BIG TCP is not supported with encryption enabled

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