caddyserver/caddy · error

%s:%d: cannot define a matcher outside of a site block: '%s'

Error message

%s:%d: cannot define a matcher outside of a site block: '%s'

What it means

Error "%s:%d: cannot define a matcher outside of a site block: '%s'" thrown in caddyserver/caddy.

Source

Thrown at caddyconfig/httpcaddyfile/httptype.go:71

// ServerType can set up a config from an HTTP Caddyfile.
type ServerType struct{}

// Setup makes a config from the tokens.
func (st ServerType) Setup(
	inputServerBlocks []caddyfile.ServerBlock,
	options map[string]any,
) (*caddy.Config, []caddyconfig.Warning, error) {
	var warnings []caddyconfig.Warning
	gc := counter{new(int)}
	state := make(map[string]any)

	// load all the server blocks and associate them with a "pile" of config values
	originalServerBlocks := make([]serverBlock, 0, len(inputServerBlocks))
	for _, sblock := range inputServerBlocks {
		for j, k := range sblock.Keys {
			if j == 0 && strings.HasPrefix(k.Text, "@") {
				return nil, warnings, fmt.Errorf("%s:%d: cannot define a matcher outside of a site block: '%s'", k.File, k.Line, k.Text)
			}
			if _, ok := registeredDirectives[k.Text]; ok {
				return nil, warnings, fmt.Errorf("%s:%d: parsed '%s' as a site address, but it is a known directive; directives must appear in a site block", k.File, k.Line, k.Text)
			}
		}
		originalServerBlocks = append(originalServerBlocks, serverBlock{
			block: sblock,
			pile:  make(map[string][]ConfigValue),
		})
	}

	// apply any global options
	var err error
	originalServerBlocks, err = st.evaluateGlobalOptionsBlock(originalServerBlocks, options)
	if err != nil {
		return nil, warnings, err
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Move the named matcher definition inside a site block, or reference an existing matcher defined at the top level with a '@name' inside a site.
2. Named matchers must be declared within a site block in the Caddyfile.

When it happens

Trigger: Thrown at caddyconfig/httpcaddyfile/httptype.go:71 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/a3ef555bbf8bc2ec. Report an issue: GitHub.