k3s-io/k3s · error

toleration with operator 'Exists' must have an empty value

Error message

toleration with operator 'Exists' must have an empty value

What it means

In Kubernetes semantics, operator 'Exists' matches any value for the given key, so carrying a Value on the same toleration is contradictory. validateToleration enforces this for tolerations parsed from the ServiceLB annotation and rejects the pair.

Source

Thrown at pkg/cloudprovider/servicelb.go:738

			return nil, fmt.Errorf("validation failed for toleration %d: %v", i, err)
		}
	}

	return tolerations, nil
}

// validateToleration ensures a toleration has valid fields according to its operator.
func validateToleration(toleration *core.Toleration) error {
	if toleration.Operator == "" {
		toleration.Operator = core.TolerationOpEqual
	}

	if toleration.Key == "" && toleration.Operator != core.TolerationOpExists {
		return errors.New("toleration with empty key must have operator 'Exists'")
	}

	if toleration.Operator == core.TolerationOpExists && toleration.Value != "" {
		return errors.New("toleration with operator 'Exists' must have an empty value")
	}

	return nil
}

// generateName generates a distinct name for the DaemonSet based on the service name and UID
func generateName(svc *core.Service) string {
	name := svc.Name
	// ensure that the service name plus prefix and uuid aren't overly long, but
	// don't cut the service name at a trailing hyphen.
	if len(name) > 48 {
		trimlen := 48
		for name[trimlen-1] == '-' {
			trimlen--
		}
		name = name[0:trimlen]
	}
	return fmt.Sprintf("svclb-%s-%s", name, svc.UID[:8])

View on GitHub (pinned to 6ba341e396)

Solutions

1. Remove the value field when using operator Exists
2. If the value matters, use the default operator Equal with key and value set
3. Lint the annotation JSON before applying (operator Exists ⇒ value must be absent/empty)

Example fix

# before
[{"key":"special","operator":"Exists","value":"true"}]

# after
[{"key":"special","operator":"Exists"}]

// reject Exists-with-value before annotating
for _, t := range parsedTolerations {
    if t.Operator == core.TolerationOpExists && t.Value != "" {
        return fmt.Errorf("toleration key=%q: operator Exists must not set value", t.Key)
    }
}

func existsTolerationHasNoValue(t core.Toleration) bool {
    return t.Operator != core.TolerationOpExists || t.Value == ""
}

When it happens

Trigger: Service annotated with `servicelb.k3s.io/tolerations: '[{"key":"foo","operator":"Exists","value":"bar"}]'` — any combination where operator is Exists and value is a non-empty string.

Common situations: Converting an Equal toleration to Exists and forgetting to delete the value field; templating engines that always emit a value field; copy-paste between annotations and pod specs that skips cleanup.

Related errors

• toleration with empty key must have operator 'Exists'
• all cloud-provider functionality disabled by config
• Failed checking netMode
• Initial server URL host is not defined for load balancer
• --server is required

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/4910fc906ffa10a8. Report an issue: GitHub.