hashicorp/nomad · error

Error querying job prefix %q: %s

Error message

Error querying job prefix %q: %s

What it means

Returned by jobIDByPrefix when the paginated prefix-list request (Jobs().PrefixList with a server-side filter) fails and the error is not the known paginator 'is not nil' filter bug from servers older than 1.11.3. Any non-paginator failure — ACL denial, bad namespace, network error — surfaces through this wrap.

Source

Thrown at command/meta.go:375

// to the results instead.
func (m *Meta) jobIDByPrefix(client *api.Client, prefix, filter string, clientFilter JobByPrefixFilterFunc) (string, string, error) {
	maxResults := 20 // reduce load for large sets
	jobs, _, err := client.Jobs().ListOptions(nil, &api.QueryOptions{
		Prefix:  prefix,
		Filter:  filter,
		PerPage: int32(maxResults),
	})
	truncated := len(jobs) >= maxResults
	if err != nil {
		if strings.Contains(err.Error(), api.PermissionDeniedErrorContent) {
			return prefix, "", nil
		}
		// Servers older than 1.11.3 reject the "is not nil" filter operator
		// while building the result paginator. Retry without the server-side
		// filter and narrow the results on the client.
		// COMPAT(2.0): remove this fallback once 1.10LTS is out of support
		if clientFilter == nil || !strings.Contains(err.Error(), api.ResultPaginatorErrorContent) {
			return "", "", fmt.Errorf("Error querying job prefix %q: %s", prefix, err)
		}
		jobs, _, err = client.Jobs().PrefixList(prefix)
		if err != nil {
			return "", "", fmt.Errorf("Error querying job prefix %q: %s", prefix, err)
		}
		var filtered []*api.JobListStub
		for _, j := range jobs {
			if clientFilter(j) {
				filtered = append(filtered, j)
			}
		}
		jobs = filtered
		truncated = false // the unfiltered prefix list is complete
	}

	if len(jobs) == 0 {
		return "", "", &NoJobWithPrefixError{Prefix: prefix}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped cause to identify 403 vs 404 vs transport failure.
2. Upgrade the Nomad servers to >=1.11.3 if you see repeated paginator-related filter errors.
3. Ensure the ACL token can list jobs in the target namespace(s).
4. Verify the -namespace/NOMAD_NAMESPACE value exists (`nomad namespace list`).
5. Check connectivity to NOMAD_ADDR and retry transient failures.

Example fix

// before: token can't list jobs in default namespace
NOMAD_TOKEN=<restricted> nomad job status web
// after
NOMAD_TOKEN=<token-with-list-jobs> nomad job status -namespace prod web

nomad namespace list >/dev/null 2>&1 || echo "cannot list: token or connectivity problem"

id, ns, err := JobIDByPrefix(client, ns, prefix, filter)
if err != nil && strings.Contains(err.Error(), "Error querying job prefix") {
    if !strings.Contains(err.Error(), api.ResultPaginatorErrorContent) {
        // genuine failure: classify 403/404/transport and act
    }
}

When it happens

Trigger: A prefix-based job resolution (e.g. `nomad job status web`) where GET /v1/jobs?prefix=... errors, and either no client-side fallback filter was supplied or the error does not contain api.ResultPaginatorErrorContent: 403 on job listing, invalid namespace, connection refused.

Common situations: Older Nomad servers (<1.11.3) hitting the paginator filter bug (that path is retried separately); tokens without list-jobs capability; typo'd namespace in -namespace flag; cluster unreachable during scripted status checks.

Related errors

• Error querying job %q: %s
• Prefix %q matched multiple jobs\n\n%s%s
• Node does not support RPC; requires 0.8 or later
• plugin loaded does not implement the driver interface
• error getting client config: %v

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