What causes "failed to register service" in micro/go-micro?

Check the wrapped cause in the error chain (%+v with stack) to see the registry-specific failure

failed to register service

Error message

failed to register service

What it means

This error is wrapped by server.Register in server/rpc_server.go when the framework's cached service registration function fails. Register is called during server Start (and by the registrar loop) to publish the service node to the configured registry. The wrapped cause is whatever the registry backend (etcd, mdns, consul, etc.) returned, so the real reason is in the error chain.

Source

Thrown at server/rpc_server.go:404

	}

	s.handlers[h.Name()] = h

	return nil
}

func (s *rpcServer) Register() error {
	config := s.Options()
	logger := config.Logger

	// Registry function used to register the service
	regFunc := s.newRegFuc(config)

	// Directly register if service was cached
	rsvc := s.getCachedService()
	if rsvc != nil {
		if err := regFunc(rsvc); err != nil {
			return errors.Wrap(err, "failed to register service")
		}

		return nil
	}

	// Only cache service if host IP valid
	addr, cacheService, err := s.getAddr(config)
	if err != nil {
		return err
	}

	node := &registry.Node{
		// TODO: node id should be set better. Add native option to specify
		// host id through either config or ENV. Also look at logging of name.
		Id:       config.Name + "-" + config.Id,
		Address:  addr,
		Metadata: s.newNodeMetedata(config),
	}

View on GitHub (pinned to 24529f1404)

Solutions

Check the wrapped cause in the error chain (%+v with stack) to see the registry-specific failure
Verify the registry backend is reachable at the configured address (curl/ping etcd or consul endpoint)
Fix registry options (addresses, auth, TLS) passed to micro.New(registry.Registry(...))
Ensure the service host/IP is resolvable and the node ID is not conflicting; retry Start after the registry recovers

Example fix

// before
micro.New(micro.Registry(registry.Registry(etcd))) // etcd not configured
// after
micro.New(micro.Registry(registry.NewRegistry(registry.Addrs("etcd:2379"))))

Defensive patterns

Strategy: retry

Validate before calling

// before starting the server
reg := registry.NewRegistry(registry.Addrs("etcd:2379"))
if _, err := reg.ListServices(); err != nil {
    return fmt.Errorf("registry unreachable: %w", err)
}

Try / catch

if err := srv.Start(); err != nil {
    var cause error
    errors.As(err, &cause) // unwrap registry cause
    log.Printf("register failed: %+v", err)
    // retry with backoff
    time.Sleep(backoff)
    err = srv.Start()
}

Prevention

Health-check the registry before calling Start
Configure registry addresses/credentials explicitly, not defaults
Run a registrar retry loop so transient registry outages self-heal
Ensure node IDs and host IPs are valid and unique

When it happens

Trigger: server.Register() invokes regFunc(rsvc) on a service returned from getCachedService(); the registry's Register call fails (backend unreachable, auth rejected, node invalid). Any caller of Start or the registrar loop that hits the cached-service path can surface this.

Common situations: Registry server (etcd/consul) not running or wrong registry address in config; missing registry credentials/TLS settings; network partition between the service and the registry; mdns failing in containerized environments without multicast.

Related errors

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/e00e84a81da6d802. Report an issue: GitHub.