{"record":{"id":"7764da2927ba0ef0","repo":"go-kratos/kratos","slug":"registerinstance-err-v-v","errorCode":null,"errorMessage":"RegisterInstance err %v,%v","messagePattern":"RegisterInstance err (.+?),(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"contrib/registry/nacos/registry.go","lineNumber":142,"sourceCode":"\t\t\t\tif err != nil {\n\t\t\t\t\tweight = r.opts.weight\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\t_, e := r.cli.RegisterInstance(vo.RegisterInstanceParam{\n\t\t\tIp:          host,\n\t\t\tPort:        uint64(p),\n\t\t\tServiceName: si.Name + \".\" + u.Scheme,\n\t\t\tWeight:      weight,\n\t\t\tEnable:      true,\n\t\t\tHealthy:     true,\n\t\t\tEphemeral:   true,\n\t\t\tMetadata:    rmd,\n\t\t\tClusterName: r.opts.cluster,\n\t\t\tGroupName:   r.opts.group,\n\t\t})\n\t\tif e != nil {\n\t\t\treturn fmt.Errorf(\"RegisterInstance err %v,%v\", e, endpoint)\n\t\t}\n\t}\n\treturn nil\n}\n\n// Deregister the registration.\nfunc (r *Registry) Deregister(_ context.Context, service *registry.ServiceInstance) error {\n\tfor _, endpoint := range service.Endpoints {\n\t\tu, err := url.Parse(endpoint)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\thost, port, err := net.SplitHostPort(u.Host)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tp, err := strconv.Atoi(port)\n\t\tif err != nil {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/go-kratos/kratos/blob/668db92c2c001e9552594ba5a8aede8456af6d7e/contrib/registry/nacos/registry.go#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log the full error - the %v part from nacos-sdk names the real cause (errCode like 403 auth, connection refused, namespace not exist)","Verify Nacos connectivity from the app container: curl http://<nacos>:8848/nacos/ and check address, port, and context path","If Nacos auth is enabled, set username/password (or accessKey/secretKey) in the nacos registry options to match the server","Confirm namespace and group in the registry options exist on the Nacos server (check the console) and match the intended namespaceID exactly","Validate each ServiceInstance endpoint parses to a real host:port (url.Parse of 'grpc://host:port') before registering"],"exampleFix":"// before: auth-enabled Nacos rejects anonymous registration\nr, _ := nacos.NewRegistry(cli, nacos.WithGroup(\"DEFAULT_GROUP\"))\n\n// after: pass credentials matching the server\nr, _ := nacos.NewRegistry(cli,\n\tnacos.WithGroup(\"DEFAULT_GROUP\"),\n\tnacos.WithUsername(\"nacos\"), nacos.WithPassword(\"nacos\"))","handlingStrategy":"try-catch","validationCode":"// Validate endpoints and connectivity before Register\nfunc preflightNacos(ins *registry.ServiceInstance, serverAddr string) error {\n\tif len(ins.Endpoints) == 0 {\n\t\treturn fmt.Errorf(\"no endpoints to register\")\n\t}\n\tfor _, ep := range ins.Endpoints {\n\t\tu, err := url.Parse(ep)\n\t\tif err != nil || u.Hostname() == \"\" {\n\t\t\treturn fmt.Errorf(\"bad endpoint %q\", ep)\n\t\t}\n\t}\n\tconn, err := net.DialTimeout(\"tcp\", serverAddr, 2*time.Second)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"nacos unreachable: %w\", err)\n\t}\n\t_ = conn.Close()\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := r.Register(ctx, ins); err != nil {\n\tif strings.Contains(err.Error(), \"RegisterInstance err\") {\n\t\t// inspect the wrapped nacos error for errCode: auth(403)/namespace/connection\n\t\tlog.Error(\"nacos registration failed\", \"err\", err, \"endpoints\", ins.Endpoints)\n\t\treturn err // configuration errors are not transient; fix before retry\n\t}\n}","preventionTips":["Keep nacos registry options (namespace, group, cluster, credentials) in one config source shared by all services","Test registration in a staging Nacos with the same auth settings as production","Confirm namespaceID exists on the server - Nacos rejects unknown namespaces","Use the Nacos console to verify instances appear after deploy; alert on registration failure at startup"],"tags":["go","kratos","nacos","service-registry","registration"],"backgroundTag":null,"analyzedSha":"668db92c2c001e9552594ba5a8aede8456af6d7e","analyzedAt":"2026-08-16T02:07:20.704Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}