coredns/coredns · error

unable to normalize '%s'

Error message

unable to normalize '%s'

What it means

parseStanza normalizes the FROM zone with plugin.Host(...).NormalizeExact(). If normalization yields zero zones, the FROM argument is not a valid DNS zone/name expression, so the stanza is rejected with "unable to normalize '%s'". This guards the plugin from running with an unparsable zone.

Source

Thrown at plugin/forward/setup.go:138

			zone = strings.TrimSuffix(zone, "]")
		}
	}
	if trans != "" {
		newHost = trans + "://" + newHost
	}
	return
}

func parseStanza(c *caddy.Controller) (*Forward, error) {
	f := New()

	if !c.Args(&f.from) {
		return f, c.ArgErr()
	}
	origFrom := f.from
	zones := plugin.Host(f.from).NormalizeExact()
	if len(zones) == 0 {
		return f, fmt.Errorf("unable to normalize '%s'", f.from)
	}
	f.from = zones[0] // there can only be one here, won't work with non-octet reverse

	if len(zones) > 1 {
		log.Warningf("Unsupported CIDR notation: '%s' expands to multiple zones. Using only '%s'.", origFrom, f.from)
	}

	to := c.RemainingArgs()
	if len(to) == 0 {
		return f, c.ArgErr()
	}

	// Parse block first to get resolver and other options before processing TO addresses.
	for c.NextBlock() {
		if err := parseBlock(c, f); err != nil {
			return f, err
		}
	}

View on GitHub (pinned to 558c9757a9)

Solutions

1. Correct the FROM argument to a valid zone, e.g. 'forward . ...' or 'forward example.org ...'.
2. Use proper reverse-notation: 'forward 10.in-addr.arpa ...' or CIDR 'forward 10.0.0.0/24 ...' with correct syntax.
3. Validate the Corefile with coredns -conf Corefile (or corefile-migration tool) before deploying.

Example fix

// before
forward .. 8.8.8.8
// after
forward . 8.8.8.8

if len(plugin.Host(from).NormalizeExact()) == 0 {
    return fmt.Errorf("invalid forward zone: %s", from)
}

When it happens

Trigger: Corefile 'forward <from> ...' where <from> is malformed: illegal characters, an invalid reverse-style name, an empty or nonsense token that NormalizeExact cannot turn into a zone.

Common situations: Typo in the zone argument; pasting an URL or path instead of a zone; invalid CIDR/reverse notation like '10.0.0/24' typos; quoting or whitespace corruption in generated Corefiles.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• more than %d TOs configured: %d
• max_age (%s) must not be less than expire (%s)
• no valid upstream addresses found
• health_check can't be negative: %d
• health_check: invalid domain name %s

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