{"record":{"id":"626ef37559d219db","repo":"k3s-io/k3s","slug":"incompatible-down-level-server-detected-servers-m","errorCode":null,"errorMessage":"incompatible down-level server detected; servers must be upgraded to at least %s, or restarted with --disable-network-policy","messagePattern":"incompatible down-level server detected; servers must be upgraded to at least (.+?), or restarted with --disable-network-policy","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/config/config.go","lineNumber":834,"sourceCode":"\t}\n\n\tcontrolControl := &config.Control{}\n\treturn controlControl, json.Unmarshal(data, controlControl)\n}\n\n// getReadyz returns nil if the server is ready, or an error if not.\nfunc getReadyz(info *clientaccess.Info) error {\n\t_, err := info.Get(\"/v1-\" + version.Program + \"/readyz\")\n\treturn err\n}\n\n// validateNetworkConfig ensures that the network configuration values provided by the server make sense.\nfunc validateNetworkConfig(nodeConfig *config.Node) error {\n\t// Old versions of the server do not send enough information to correctly start the NPC. Users\n\t// need to upgrade the server to at least the same version as the agent, or disable the NPC\n\t// cluster-wide.\n\tif !nodeConfig.AgentConfig.DisableNPC && (nodeConfig.AgentConfig.ServiceCIDR == nil || nodeConfig.AgentConfig.ServiceNodePortRange.Size == 0) {\n\t\treturn fmt.Errorf(\"incompatible down-level server detected; servers must be upgraded to at least %s, or restarted with --disable-network-policy\", version.Version)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":816,"sourceCodeEnd":839,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/config/config.go#L816-L839","documentation":"validateNetworkConfig runs on the agent and refuses to start the network policy controller when the server-supplied config is incomplete: if DisableNPC is false and either ServiceCIDR is nil or ServiceNodePortRange.Size == 0, the server is declared down-level. Old servers do not send these fields; running the NPC without them would misconfigure network policy, so the agent aborts with the minimum version it needs.","triggerScenarios":"An agent at version X talking to a server older than X (server omits serviceCIDR / service-node-port-range from the /v1-<program>/configs payload) while network policy is enabled (server not started with --disable-network-policy).","commonSituations":"Rolling upgrades where agents were upgraded before servers; a new-version agent joining an old-version server; a downgraded or version-pinned server behind the load balancer.","solutions":["Upgrade the server to at least the version printed in the error (the agent's version.Version), then restart it","Or restart the server with --disable-network-policy to run the cluster without the NPC","For rolling upgrades: upgrade servers first, then agents"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before enabling the NPC on a new agent, confirm the server sends the needed fields:\n// fetch the agent config from the server; if ServiceCIDR == nil or\n// ServiceNodePortRange.Size == 0, upgrade the server first or start it with\n// --disable-network-policy.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Upgrade servers before agents in every rolling upgrade","Pin agent versions to <= server version until the server is upgraded","If agents must outpace the server temporarily, run the server with --disable-network-policy"],"tags":["versioning","upgrade","network-policy","agent","server"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}