coredns/coredns · error

unknown flag action=%s, should be set or clear

Error message

unknown flag action=%s, should be set or clear

What it means

Configuration error in the header plugin's newRules. The action keyword is neither 'set' nor 'clear' (case-insensitive), so the rule's boolean state cannot be determined; Corefile setup fails with the offending action named.

Source

Thrown at plugin/header/header.go:63

func newRules(key string, args []string) ([]Rule, error) {
	if key == "" {
		return nil, fmt.Errorf("no flag action provided")
	}

	if len(args) < 1 {
		return nil, fmt.Errorf("invalid length for flags, at least one should be provided")
	}

	var state bool
	action := strings.ToLower(key)
	switch action {
	case "set":
		state = true
	case "clear":
		state = false
	default:
		return nil, fmt.Errorf("unknown flag action=%s, should be set or clear", action)
	}

	rules := make([]Rule, 0, len(args))
	for _, arg := range args {
		flag := strings.ToLower(arg)
		switch flag {
		case authoritative:
		case recursionAvailable:
		case recursionDesired:
		default:
			return nil, fmt.Errorf("unknown/unsupported flag=%s", flag)
		}
		rule := Rule{Flag: flag, State: state}
		rules = append(rules, rule)
	}

	return rules, nil
}

View on GitHub (pinned to 558c9757a9)

Solutions

1. Use only 'set' or 'clear' as the action keyword.
2. Fix typos in the action word (check the error's action=%s value).
3. Consult the header plugin documentation for supported actions and flags.

Example fix

// before
header {
    unset DO
}
// after
header {
    clear DO
}

switch strings.ToLower(action) {
case "set", "clear":
    // ok
default:
    return fmt.Errorf("unsupported header action %q; use set or clear", action)
}

When it happens

Trigger: A header stanza uses an unsupported action keyword, e.g. 'header { add DO }' or 'unset DO'.

Common situations: Users guess at action names borrowed from other plugins/HTTP header tools ('add', 'delete', 'unset'); typos like 'ste' or 'claer'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• no flag action provided
• invalid length for flags, at least one should be provided
• no forwarder defined
• this plugin can only be used once per Server Block
• more than %d TOs configured: %d

AI-assisted analysis of coredns/coredns@558c9757a9 (2026-09-06). Data as JSON: /api/errors/0af8eed31576ccbb. Report an issue: GitHub.