evanw/esbuild · error

[ ] is missing a filter

Error message

[%s] %q is missing a filter

What it means

Thrown by esbuild's CompileFilterForPlugin when a plugin's OnResolve or OnLoad registration passes an empty string as the filter argument. esbuild plugins require a non-empty Go RE2 regular expression for every filter so that the callback knows which import paths to intercept. The %s is the plugin name and %q is the 'filter' or 'namespace' kind label.

Solutions

1. Provide a non-empty Go RE2 regex string as the filter, e.g. '.*' to match all paths or '.+\.svg$' for specific extensions
2. If your plugin should match every import, use the regex '.*'
3. If the filter is computed dynamically, add a guard that falls back to '.*' when the computed value is empty

Example fix

// before
build.onResolve({ filter: '' }, handler)
// after
build.onResolve({ filter: '.*' }, handler)

function validatePluginFilter(filter) {
  if (!filter || filter.trim() === '') {
    throw new Error('Plugin filter must be a non-empty string')
  }
}
validatePluginFilter(myFilter)
build.onResolve({ filter: myFilter || '.*' }, handler)

When it happens

Trigger: Registering a plugin and calling build.onResolve({ filter: '' }, handler) or build.onLoad({ filter: '' }, handler) with an empty filter string in the setup callback.

Common situations: Plugin authors who dynamically construct a filter regex that evaluates to an empty string at runtime, or who copy a plugin template and forget to fill in the filter field.

Related errors

• [ ] filter is not a valid Go regular expression
• Cannot serve without an output path
• Invalid charset
• Invalid color
• Invalid engine name

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/1cfb89bba5c3a3af. Report an issue: GitHub.

Appendix: source

Thrown at internal/config/config.go:758

	// Cache miss
	result, err := regexp.Compile(filter)
	if err != nil {
		return nil
	}

	// Cache for next time
	filterMutex.Lock()
	defer filterMutex.Unlock()
	if filterCache == nil {
		filterCache = make(map[string]*regexp.Regexp)
	}
	filterCache[filter] = result
	return
}

func CompileFilterForPlugin(pluginName string, kind string, filter string) (*regexp.Regexp, error) {
	if filter == "" {
		return nil, fmt.Errorf("[%s] %q is missing a filter", pluginName, kind)
	}

	result := compileFilter(filter)
	if result == nil {
		return nil, fmt.Errorf("[%s] %q filter is not a valid Go regular expression: %q", pluginName, kind, filter)
	}

	return result, nil
}

func PluginAppliesToPath(path logger.Path, filter *regexp.Regexp, namespace string) bool {
	return (namespace == "" || path.Namespace == namespace) && filter.MatchString(path.Text)
}

////////////////////////////////////////////////////////////////////////////////
// Plugin API

type Plugin struct {

View on GitHub (pinned to f6058f8364)