What causes "service %s not found in registry" in go-kratos/kratos?

Retry with backoff — usually transient while instances re-register during deploys

service %s not found in registry

Error message

service %s not found in registry

What it means

Consul registry GetService with an existing watch set whose snapshot is currently empty: the code falls back to a live Consul query and, still finding nothing, returns 'not found in registry'. The service was known before but has zero available endpoints right now.

Source

Thrown at contrib/registry/consul/registry.go:169

		services, _, err := r.cli.Service(ctx, name, 0, true)
		if err == nil && len(services) > 0 {
			return services
		}
		return nil
	}

	if set == nil {
		if s := getRemote(); len(s) > 0 {
			return s, nil
		}
		return nil, fmt.Errorf("service %s not resolved in registry", name)
	}
	ss, _ := set.services.Load().([]*registry.ServiceInstance)
	if ss == nil {
		if s := getRemote(); len(s) > 0 {
			return s, nil
		}
		return nil, fmt.Errorf("service %s not found in registry", name)
	}
	return ss, nil
}

// ListServices return service list.
func (r *Registry) ListServices() (allServices map[string][]*registry.ServiceInstance, err error) {
	r.lock.RLock()
	defer r.lock.RUnlock()
	allServices = make(map[string][]*registry.ServiceInstance)
	for name, set := range r.registry {
		ss, _ := set.services.Load().([]*registry.ServiceInstance)
		if ss == nil {
			continue
		}
		services := make([]*registry.ServiceInstance, 0, len(ss))
		services = append(services, ss...)
		allServices[name] = services
	}

View on GitHub (pinned to 668db92c2c)

Solutions

Retry with backoff — usually transient while instances re-register during deploys
Verify instance health in Consul and investigate why all checks or registrations dropped
Add consumer-side circuit breaking and fallback so empty resolution degrades gracefully

Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: verify healthy instances exist before depending on the service
svcs, _, err := consulClient.Health().Service(name, "", true, nil)
if err != nil {
    return err
}
if len(svcs) == 0 {
    return fmt.Errorf("no healthy instances for %s yet", name)
}

Try / catch

for attempt := 0; attempt < maxAttempts; attempt++ {
    ins, err := reg.GetService(ctx, name)
    if err == nil {
        return ins
    }
    if strings.Contains(err.Error(), "not found in registry") {
        time.Sleep(backoff(attempt)) // transient during re-registration
        continue
    }
    return nil, err
}

Prevention

Avoid scale-to-zero for critical dependencies
Keep last-known endpoints in the consumer's connection pool during blips
Watch registry events instead of polling to react to re-registration faster

When it happens

Trigger: GetService(ctx, name) where the watch set exists but its atomic services snapshot is nil (all instances deregistered) and the fallback live query also returns nothing.

Common situations: Rolling restarts deregistering all instances briefly; flapping health checks; scale-to-zero; maintenance windows; network partition between app and Consul agents.

Related errors

AI-assisted analysis of go-kratos/kratos@668db92c2c (2026-08-16). Data as JSON: /api/errors/8bdc4243c383b023. Report an issue: GitHub.