hashicorp/nomad · error

fuzzy search is not enabled

Error message

fuzzy search is not enabled

What it means

Nomad's fuzzy search API (FuzzySearch RPC) is an opt-in feature controlled by the server config SearchConfig.FuzzyEnabled. The server rejects fuzzy search RPCs with this error when the feature flag is off, even if permissions are valid. It protects servers from the extra resource cost of fuzzy matching until an operator explicitly enables it.

Source

Thrown at nomad/search_endpoint.go:752

		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "search", "fuzzy_search"}, time.Now())

	aclObj, err := s.srv.ResolveACL(args)
	if err != nil {
		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,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set `search { fuzzy_enabled = true }` in the Nomad server configuration block and restart/roll the servers
2. Fall back to the non-fuzzy Search RPC (context + prefix matching) which is always enabled
3. If the flag cannot be changed, filter results client-side from prefix search results instead

Example fix

// before (server config)
server { enabled = true }
// after
server {
  enabled = true
  search {
    fuzzy_enabled = true
    min_term_length = 2
  }
}

// Before issuing a fuzzy search, check the server advertises the feature
// or probe once and cache the capability:
resp, err := client.Search().FuzzySearch(ctx, &api.SearchRequest{Text: "probe-prefix", Context: "jobs"})
if err != nil && strings.Contains(err.Error(), "fuzzy search is not enabled") {
    fuzzyEnabled = false // fall back to prefix search
}

resp, err := client.Search().FuzzySearch(ctx, req)
if err != nil {
    if strings.Contains(err.Error(), "fuzzy search is not enabled") {
        resp, err = client.Search().Get(ctx, req) // prefix-search fallback
    }
    if err != nil { return err }
}

When it happens

Trigger: Calling the Search.FuzzySearch RPC (e.g. via `nomad search -fuzzy` or the API POST /v1/search/fuzzy) on a server whose config.SearchConfig.FuzzyEnabled is false (the default).

Common situations: Operators upgrading Nomad and trying the fuzzy search endpoint without adding search { fuzzy_enabled = true } to the server config; CI/tools assuming fuzzy search is on by default; enterprise/oss clusters where the flag was never set in the server hcl.

Related errors

• dynamic workload users disabled
• only one server.keyring can be active in Nomad Community Edi
• timeout cannot be negative
• Interval cannot be less than %v (got %v)
• Nomad can only make %v attempts in %v with initial delay %v

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