go-kratos/kratos · error

RegisterInstance err %v,%v

Error message

RegisterInstance err %v,%v

What it means

Wrapped error from the Kratos Nacos registry when the underlying nacos-sdk-go NamingClient.RegisterInstance call fails for a single endpoint; the message includes both the SDK error and the endpoint (host:port) being registered. Each endpoint of a ServiceInstance is registered as a separate Nacos instance named service.Name + "." + URL scheme, with the configured cluster and group.

Source

Thrown at contrib/registry/nacos/registry.go:142

				if err != nil {
					weight = r.opts.weight
				}
			}
		}
		_, e := r.cli.RegisterInstance(vo.RegisterInstanceParam{
			Ip:          host,
			Port:        uint64(p),
			ServiceName: si.Name + "." + u.Scheme,
			Weight:      weight,
			Enable:      true,
			Healthy:     true,
			Ephemeral:   true,
			Metadata:    rmd,
			ClusterName: r.opts.cluster,
			GroupName:   r.opts.group,
		})
		if e != nil {
			return fmt.Errorf("RegisterInstance err %v,%v", e, endpoint)
		}
	}
	return nil
}

// Deregister the registration.
func (r *Registry) Deregister(_ context.Context, service *registry.ServiceInstance) error {
	for _, endpoint := range service.Endpoints {
		u, err := url.Parse(endpoint)
		if err != nil {
			return err
		}
		host, port, err := net.SplitHostPort(u.Host)
		if err != nil {
			return err
		}
		p, err := strconv.Atoi(port)
		if err != nil {

View on GitHub (pinned to 668db92c2c)

Solutions

1. Log the full error - the %v part from nacos-sdk names the real cause (errCode like 403 auth, connection refused, namespace not exist)
2. Verify Nacos connectivity from the app container: curl http://<nacos>:8848/nacos/ and check address, port, and context path
3. If Nacos auth is enabled, set username/password (or accessKey/secretKey) in the nacos registry options to match the server
4. Confirm namespace and group in the registry options exist on the Nacos server (check the console) and match the intended namespaceID exactly
5. Validate each ServiceInstance endpoint parses to a real host:port (url.Parse of 'grpc://host:port') before registering

Example fix

// before: auth-enabled Nacos rejects anonymous registration
r, _ := nacos.NewRegistry(cli, nacos.WithGroup("DEFAULT_GROUP"))

// after: pass credentials matching the server
r, _ := nacos.NewRegistry(cli,
	nacos.WithGroup("DEFAULT_GROUP"),
	nacos.WithUsername("nacos"), nacos.WithPassword("nacos"))

// Validate endpoints and connectivity before Register
func preflightNacos(ins *registry.ServiceInstance, serverAddr string) error {
	if len(ins.Endpoints) == 0 {
		return fmt.Errorf("no endpoints to register")
	}
	for _, ep := range ins.Endpoints {
		u, err := url.Parse(ep)
		if err != nil || u.Hostname() == "" {
			return fmt.Errorf("bad endpoint %q", ep)
		}
	}
	conn, err := net.DialTimeout("tcp", serverAddr, 2*time.Second)
	if err != nil {
		return fmt.Errorf("nacos unreachable: %w", err)
	}
	_ = conn.Close()
	return nil
}

if err := r.Register(ctx, ins); err != nil {
	if strings.Contains(err.Error(), "RegisterInstance err") {
		// inspect the wrapped nacos error for errCode: auth(403)/namespace/connection
		log.Error("nacos registration failed", "err", err, "endpoints", ins.Endpoints)
		return err // configuration errors are not transient; fix before retry
	}
}

When it happens

Trigger: Registry.Register() with endpoints the Nacos server rejects or cannot be reached for: server address/port wrong, Nacos auth enabled but username/password (or accessToken) missing, namespace or group not matching what is configured server-side, service name containing characters Nacos rejects, or network/DNS failure to the Nacos endpoint.

Common situations: Nacos 2.x with auth enabled (identity key/value or username/password) while the registry options were set for anonymous access; wrong namespaceID in WithNamespace so registration lands on a nonexistent namespace; group name mismatch (DEFAULT_GROUP vs custom); endpoints like grpc://host:port where the parsed host is empty or unresolvable; Nacos behind a gateway that requires a context path.

Related errors

• ErrorCode: %d
• response Error %d
• retry after %d times
• unsupported key: %s format: %s
• invalid path: %q is not a message

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