hashicorp/nomad · error

fuzzy search query must be at least %d characters, got %d

Error message

fuzzy search query must be at least %d characters, got %d

What it means

When fuzzy search is enabled, Nomad enforces a minimum length on the query term, configurable via SearchConfig.MinTermLength. The FuzzySearch RPC returns this error when len(args.Text) is shorter than that minimum. This prevents extremely short, high-fan-out fuzzy queries that are expensive to evaluate across all contexts.

Source

Thrown at nomad/search_endpoint.go:758

		return err
	}

	namespace := args.RequestNamespace()
	context := args.Context

	if !sufficientFuzzySearchPerms(aclObj, namespace, context) {
		return structs.ErrPermissionDenied
	}

	// check that fuzzy search API is enabled
	if !s.srv.config.SearchConfig.FuzzyEnabled {
		return fmt.Errorf("fuzzy search is not enabled")
	}

	// check the query term meets minimum length
	min := s.srv.config.SearchConfig.MinTermLength
	if n := len(args.Text); n < min {
		return fmt.Errorf("fuzzy search query must be at least %d characters, got %d", min, n)
	}

	// for case-insensitive searching, lower-case the search term once and reuse
	text := strings.ToLower(args.Text)

	// accumulate fuzzy search results and any truncations
	reply.Matches = make(map[structs.Context][]structs.FuzzyMatch)
	reply.Truncations = make(map[structs.Context]bool)

	// Setup the blocking query
	opts := blockingOptions{
		queryMeta: &reply.QueryMeta,
		queryOpts: new(structs.QueryOptions),
		run: func(ws memdb.WatchSet, state *state.StateStore) error {

			fuzzyIters := make(map[structs.Context]memdb.ResultIterator)
			prefixIters := make(map[structs.Context]memdb.ResultIterator)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Send a query term at least MinTermLength characters long (default is 2 or the operator-configured value)
2. Lower `search { min_term_length = N }` in server config if short terms are legitimately needed
3. Check len(text) client-side and skip/warn before issuing the RPC

Example fix

// before
req := &api.SearchRequest{Text: "jo", Context: "jobs"}
// after
if len("jo") < minTermLength { /* pad or reject client-side */ }
req := &api.SearchRequest{Text: "job-prefix", Context: "jobs"}

const minTermLength = 2 // match server SearchConfig.MinTermLength
if len(req.Text) < minTermLength {
    return fmt.Errorf("query must be at least %d characters", minTermLength)
}

resp, err := client.Search().FuzzySearch(ctx, req)
if err != nil {
    if strings.Contains(err.Error(), "must be at least") {
        return errFuzzyTermTooShort{Term: req.Text}
    }
    return err
}

When it happens

Trigger: Sending a FuzzySearch request whose Text field is shorter than s.srv.config.SearchConfig.MinTermLength (default minimum) — e.g. searching for "a" or an empty string.

Common situations: Users typing 1-2 characters into a UI search box wired to fuzzy search; programmatic callers passing empty Text; clusters where operators raised MinTermLength above what existing clients send.

Related errors

• Missing job ID
• Job ID contains a space
• Job ID contains a null character
• Missing job name
• Job Name contains a null character

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/4a865b6397770d03. Report an issue: GitHub.