gohugoio/hugo · error

empty deployment matcher

Error message

empty deployment matcher

What it means

Each entry in deployment.matchers is compared to the zero-value Matcher{}. An entry with no fields at all (no pattern, no cacheControl, etc.) is rejected. A matcher that has a pattern is fine even if other fields are unset.

Solutions

1. Give every [[deployment.matchers]] entry at least a `pattern` plus the headers/Cache-Control you want.
2. Remove empty/placeholder matcher entries.
3. Check config indentation so each matcher decodes with its fields.

Example fix

// before
[[deployment.matchers]]
# (no fields)
// after
[[deployment.matchers]]
pattern = ".+\\.js$"
Cache-Control = "public, max-age=31536000"

// Reject empty matcher entries before deploying
for _, m := range matchers {
    if m == (Matcher{}) {
        return errors.New("empty deployment matcher found; add a pattern")
    }
}

When it happens

Trigger: A `[[deployment.matchers]]` table with no keys, leaving a completely empty matcher.

Common situations: Placeholder matcher left in config; indentation/formatting error producing an empty map; stub added while drafting CDN header rules.

Related errors

• empty deployment target
• no deployment targets found
• aborted
• --appendPort=false not supported when in multihost mode
• cache dir contains unresolved placeholders

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/83808f415e07bab2. Report an issue: GitHub.

Appendix: 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 52c9bd7908)