What causes "empty deployment matcher" in gohugoio/hugo?

Remove the empty `[[deployment.matchers]]` block from your config, or add at least `pattern = "..."` to it.

empty deployment matcher

Error message

empty deployment matcher

What it means

Raised in DecodeConfig (deploy/deployconfig/deployConfig.go:163) while decoding the `[deployment]` section of Hugo's config. Each entry in `deployment.matchers` is checked against the zero-value Matcher struct; if none of its fields (pattern, cacheControl, contentEncoding, contentType, gzip, force) are set, Hugo refuses the config because an empty matcher would match nothing and indicates a typo or malformed TOML/YAML block.

Source

Thrown at deploy/deployconfig/deployConfig.go:163

		return dcfg, err
	}

	if dcfg.Workers <= 0 {
		dcfg.Workers = 10
	}

	for _, tgt := range dcfg.Targets {
		if *tgt == (Target{}) {
			return dcfg, errors.New("empty deployment target")
		}
		if err := tgt.ParseIncludeExclude(); err != nil {
			return dcfg, err
		}
	}
	var err error
	for _, m := range dcfg.Matchers {
		if *m == (Matcher{}) {
			return dcfg, errors.New("empty deployment matcher")
		}
		m.Re, err = regexp.Compile(m.Pattern)
		if err != nil {
			return dcfg, fmt.Errorf("invalid deployment.matchers.pattern: %v", err)
		}
	}
	for _, o := range dcfg.Order {
		re, err := regexp.Compile(o)
		if err != nil {
			return dcfg, fmt.Errorf("invalid deployment.orderings.pattern: %v", err)
		}
		dcfg.Ordering = append(dcfg.Ordering, re)
	}

	return dcfg, nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Remove the empty `[[deployment.matchers]]` block from your config, or add at least `pattern = "..."` to it.
Check for misspelled/mis-indented keys under deployment.matchers — every key must decode into a Matcher field (pattern, cacheControl, contentEncoding, contentType, gzip, force).
Validate the config structure with `hugo config | grep -A10 deployment` to see what actually decoded.

Example fix

# before
[[deployment.matchers]]

# after
[[deployment.matchers]]
pattern = "^.+\\.(js|css|svg|ttf)$"
cacheControl = "max-age=31536000, no-transform, public"
gzip = true

Defensive patterns

Strategy: validation

Validate before calling

for i, m := range cfg.Deployment.Matchers {
    if m.Pattern == "" {
        return fmt.Errorf("deployment.matchers[%d]: pattern must be non-empty", i)
    }
}

Prevention

Never emit an empty [[deployment.matchers]] table in hugo.toml; every matcher needs a pattern key
Lint your deployment config in CI with `hugo deploy --dryRun` before real deploys
When generating config programmatically, skip matcher entries whose pattern is blank instead of writing them

When it happens

Trigger: Running `hugo deploy` (or any command that decodes site config with a deployment section) where a `[[deployment.matchers]]` table exists but contains no recognized keys, e.g. an empty `[[deployment.matchers]]` block or keys misspelled/mis-nested so mapstructure decodes them into nothing.

Common situations: Leaving a stub `[[deployment.matchers]]` block after deleting its contents; indenting matcher keys wrongly in YAML so they attach to the wrong level; typos like `patern` that leave the struct empty; copy-pasting docs examples partially.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/83808f415e07bab2.json. Report an issue: GitHub ↗.