What causes "invalid matching RCODE '%s' for a rcode rule" in coredns/coredns?

Use a valid RCODE name: NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMP, REFUSED, etc.

invalid matching RCODE '%s' for a rcode rule

Error message

invalid matching RCODE '%s' for a rcode rule

What it means

newRCodeRule validates both RCODEs with isValidRCode, which only accepts symbolic names or numeric codes the DNS library knows. If the FROM (matching) RCODE string is not a valid RCODE identifier, plugin setup fails with this message.

Source

Thrown at plugin/rewrite/rcode.go:120

func (rule *regexRCodeRule) Rewrite(_ctx context.Context, state request.Request) (ResponseRules, Result) {
	return rule.responseRule(len(rule.Pattern.FindStringSubmatch(state.Name())) != 0)
}

// newRCodeRule creates a name matching rule based on exact, partial, or regex match
func newRCodeRule(nextAction string, args ...string) (Rule, error) {
	if len(args) < 3 {
		return nil, fmt.Errorf("too few (%d) arguments for a rcode rule", len(args))
	}
	var oldStr, newStr string
	if len(args) == 3 {
		oldStr, newStr = args[1], args[2]
	}
	if len(args) == 4 {
		oldStr, newStr = args[2], args[3]
	}
	old, valid := isValidRCode(oldStr)
	if !valid {
		return nil, fmt.Errorf("invalid matching RCODE '%s' for a rcode rule", oldStr)
	}
	new, valid := isValidRCode(newStr)
	if !valid {
		return nil, fmt.Errorf("invalid replacement RCODE '%s' for a rcode rule", newStr)
	}
	if len(args) == 4 {
		switch strings.ToLower(args[0]) {
		case ExactMatch:
			return &exactRCodeRule{
				newRCodeRuleBase(nextAction, old, new),
				plugin.Name(args[1]).Normalize(),
			}, nil
		case PrefixMatch:
			return &prefixRCodeRule{
				newRCodeRuleBase(nextAction, old, new),
				plugin.Name(args[1]).Normalize(),
			}, nil
		case SuffixMatch:

View on GitHub (pinned to 558c9757a9)

Solutions

Use a valid RCODE name: NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMP, REFUSED, etc.
Or use the corresponding valid numeric RCODE value
Check the exact spelling against dns.MessageRcode mappings

Example fix

# before
rewrite stop rcode NXDOMAINR NOERROR
# after
rewrite stop rcode NXDOMAIN NOERROR

Defensive patterns

Strategy: validation

Validate before calling

var validRCODEs = map[string]bool{
	"NOERROR": true, "FORMERR": true, "SERVFAIL": true, "NXDOMAIN": true,
	"NOTIMP": true, "REFUSED": true, "YXDOMAIN": true, "YXRRSET": true,
	"NXRRSET": true, "NOTAUTH": true, "BADSIG": true, "BADKEY": true,
	"BADTIME": true, "BADMODE": true, "BADNAME": true, "BADALG": true,
	"BADTRUNC": true, "BADCOOKIE": true,
}
func validRCODE(s string) bool { return validRCODEs[s] }

Prevention

Copy RCODE names from the dns package constants instead of typing them
Spell-check RCODE mnemonics in config review
Use numeric codes only when the mapping is confirmed valid

When it happens

Trigger: `rewrite stop rcode NXDOMAINR NOERROR` or `rewrite stop rcode 99 NOERROR` — an unknown symbolic name or out-of-range numeric code supplied as the match RCODE.

Common situations: Misspelled RCODE names (NXDOMIAN, SERVFAIL typos); using names not in the supported set; confusion between mnemonic and numeric forms.

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

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