{"record":{"id":"8d080a5a7af8717e","repo":"GoogleCloudPlatform/microservices-demo","slug":"grpc-failed-to-connect-s","errorCode":null,"errorMessage":"grpc: failed to connect %s","messagePattern":"grpc: failed to connect (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/checkoutservice/main.go","lineNumber":218,"sourceCode":"}\n\nfunc mustMapEnv(target *string, envKey string) {\n\tv := os.Getenv(envKey)\n\tif v == \"\" {\n\t\tpanic(fmt.Sprintf(\"environment variable %q not set\", envKey))\n\t}\n\t*target = v\n}\n\nfunc mustConnGRPC(ctx context.Context, conn **grpc.ClientConn, addr string) {\n\tvar err error\n\t_, cancel := context.WithTimeout(ctx, time.Second*3)\n\tdefer cancel()\n\t*conn, err = grpc.NewClient(addr,\n\t\tgrpc.WithTransportCredentials(insecure.NewCredentials()),\n\t\tgrpc.WithStatsHandler(otelgrpc.NewClientHandler()))\n\tif err != nil {\n\t\tpanic(errors.Wrapf(err, \"grpc: failed to connect %s\", addr))\n\t}\n}\n\nfunc (cs *checkoutService) Check(ctx context.Context, req *healthpb.HealthCheckRequest) (*healthpb.HealthCheckResponse, error) {\n\treturn &healthpb.HealthCheckResponse{Status: healthpb.HealthCheckResponse_SERVING}, nil\n}\n\nfunc (cs *checkoutService) Watch(req *healthpb.HealthCheckRequest, ws healthpb.Health_WatchServer) error {\n\treturn status.Errorf(codes.Unimplemented, \"health check via Watch not implemented\")\n}\n\nfunc (cs *checkoutService) PlaceOrder(ctx context.Context, req *pb.PlaceOrderRequest) (*pb.PlaceOrderResponse, error) {\n\tlog.Infof(\"[PlaceOrder] user_id=%q user_currency=%q\", req.UserId, req.UserCurrency)\n\n\torderID, err := uuid.NewUUID()\n\tif err != nil {\n\t\treturn nil, status.Errorf(codes.Internal, \"failed to generate order uuid\")\n\t}","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/GoogleCloudPlatform/microservices-demo/blob/72ba613a05f7fcee51cf1d0badff401b6ae7074d/src/checkoutservice/main.go#L200-L236","documentation":"mustConnGRPC in checkoutservice creates a gRPC client connection via grpc.NewClient and panics with errors.Wrapf(err, \"grpc: failed to connect %s\", addr) if connection setup fails. Because NewClient is lazy, this error usually reflects an invalid target address (unparsable host/port, bad scheme) rather than a live-dial failure. Called from main and initTracing, a panic here means the checkout service cannot start.","triggerScenarios":"grpc.NewClient(addr, insecure creds, otel stats handler) returns err: malformed/unresolvable service address (empty env var, bad DNS name, missing port), or unsupported scheme in the target string.","commonSituations":"Required *_SERVICE_ADDR env var not set or empty in the deployment manifest; Kubernetes service name typo; port omitted from the address; wrong DNS in a different namespace; migrating from grpc.Dial to grpc.NewClient with a target string format the resolver rejects.","solutions":["Verify the address env var (e.g. SHIPPING_SERVICE_ADDR / PAYMENT_SERVICE_ADDR) is set to host:port","Confirm the target service exists and DNS resolves from the checkout pod (nslookup)","Check kubernetes service name and namespace match the configured address","Ensure the port matches the gRPC container port, not the plain HTTP one","Test the address string format (scheme/host:port) accepted by grpc.NewClient"],"exampleFix":"// before\n*conn, err = grpc.NewClient(addr, ...)\nif err != nil {\n    panic(errors.Wrapf(err, \"grpc: failed to connect %s\", addr))\n}\n// after\nif addr == \"\" {\n    panic(\"grpc: target address is empty — set the service addr env var\")\n}\n*conn, err = grpc.NewClient(addr, ...)\nif err != nil {\n    panic(errors.Wrapf(err, \"grpc: failed to create client for %s\", addr))\n}","handlingStrategy":"validation","validationCode":"if addr == \"\" {\n    panic(\"grpc: service address env var is empty\")\n}\nif _, _, err := net.SplitHostPort(addr); err != nil {\n    panic(fmt.Sprintf(\"grpc: invalid target %q: %v\", addr, err))\n}","typeGuard":null,"tryCatchPattern":"defer func() {\n    if r := recover(); r != nil {\n        log.Fatalf(\"checkout startup failed: %v\", r)\n    }\n}()","preventionTips":["Fail fast at startup if required *_SERVICE_ADDR env vars are unset","Validate address format (host:port) before grpc.NewClient","Use Kubernetes DNS names and verify with nslookup from the pod","Keep target strings scheme-resolver compatible with grpc.NewClient"],"tags":["grpc","golang","configuration","startup","connection"],"backgroundTag":"grpc-failed-to-connect","analyzedSha":"72ba613a05f7fcee51cf1d0badff401b6ae7074d","analyzedAt":"2026-09-02T01:15:09.673Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}