hashicorp/nomad · error

unknown checks namespace: %q

Error message

unknown checks namespace: %q

What it means

UpdateTTLOpts is a MockAgent (test double for the Consul agent API) that simulates TTL check updates. It looks up the check by namespace (derived from QueryOptions or default) and returns this error when no check map exists for that namespace — i.e. the test fixture never registered any checks in that namespace.

Source

Thrown at command/agent/consul/catalog_testing.go:395

		if v.ServiceID == serviceID {
			delete(c.checks[namespace], k)
			delete(c.checkTTLs[namespace], k)
		}
	}
	return nil
}

// UpdateTTLOpts implements AgentAPI
func (c *MockAgent) UpdateTTLOpts(id string, output string, status string, q *api.QueryOptions) error {
	c.mu.Lock()
	defer c.mu.Unlock()

	c.hits++
	namespace := getNamespace(q)

	checks, nsExists := c.checks[namespace]
	if !nsExists {
		return fmt.Errorf("unknown checks namespace: %q", namespace)
	}

	check, checkExists := checks[id]
	if !checkExists {
		return fmt.Errorf("unknown check: %s/%s", namespace, id)
	}

	// Flip initial status to passing
	// todo(shoenig) why not just set to the given status?
	check.Status = "passing"
	c.checkTTLs[namespace][id]++

	return nil
}

// a convenience method for looking up a registered service by name
func (c *MockAgent) lookupService(namespace, name string) []*api.AgentServiceRegistration {
	c.mu.Lock()

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Register the check in the mock under the expected namespace before calling UpdateTTLOpts (use the mock's check-registration method)
  2. Make the test's QueryOptions.Namespace match the namespace used when seeding c.checks
  3. If the default namespace was intended, pass nil QueryOptions or set the namespace the fixture seeded
  4. Inspect getNamespace to confirm how the namespace is derived and align fixture and caller

Example fix

// before
mock := NewMockAgent()
mock.UpdateTTLOpts("check-1", "", "pass", &api.QueryOptions{Namespace: "team-a"})

// after
mock := NewMockAgent()
mock.AddCheck("check-1", "team-a") // seed checks["team-a"] first
mock.UpdateTTLOpts("check-1", "", "pass", &api.QueryOptions{Namespace: "team-a"})
Defensive patterns

Strategy: try-catch

Validate before calling

func canUpdateTTL(mock *MockAgent, id string, q *api.QueryOptions) bool {
	ns := getNamespace(q)
	mock.mu.Lock()
	defer mock.mu.Unlock()
	_, nsOK := mock.checks[ns]
	return nsOK
}

Type guard

func namespaceExists(mock *MockAgent, q *api.QueryOptions) bool {
	ns := getNamespace(q)
	_, ok := mock.checks[ns]
	return ok
}

Try / catch

if err := mock.UpdateTTLOpts(id, out, "pass", q); err != nil {
	if strings.HasPrefix(err.Error(), "unknown checks namespace") {
		t.Fatalf("fixture missing namespace; seed checks for %q before updating TTL", getNamespace(q))
	}
	t.Fatal(err)
}

Prevention

When it happens

Trigger: Calling MockAgent.UpdateTTLOpts with a QueryOptions whose Namespace resolves to a namespace not present in the mock's c.checks map — typically because the test never called the mock's check-registration/setup path for that namespace before updating its TTL.

Common situations: Unit tests passing an explicit namespace (Consul Enterprise namespaces) that the fixture didn't seed; tests copied from single-namespace setups and updated to use namespaces without updating fixture setup; getNamespace defaulting differently than expected when q is nil or has an empty namespace.

Related errors

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