{"record":{"id":"2b47bf48c657b193","repo":"dapr/dapr","slug":"failed-to-start-internal-grpc-server-w","errorCode":null,"errorMessage":"failed to start internal gRPC server: %w","messagePattern":"failed to start internal gRPC server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/runtime/runtime.go","lineNumber":847,"sourceCode":"\n\t// Start HTTP Server\n\terr = a.startHTTPServer(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to start HTTP server: %w\", err)\n\t}\n\n\tif a.runtimeConfig.unixDomainSocket != \"\" {\n\t\tlog.Info(\"HTTP server is running on a Unix Domain Socket\")\n\t} else {\n\t\tlog.Infof(\"HTTP server is running on port %v\", a.runtimeConfig.httpPort)\n\t}\n\n\tlog.Infof(\"The request body size parameter is: %v bytes\", a.runtimeConfig.maxRequestBodySize)\n\n\t// Start internal gRPC server (used for sidecar-to-sidecar communication)\n\terr = a.startGRPCInternalServer(ctx, a.daprGRPCAPI)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to start internal gRPC server: %w\", err)\n\t}\n\n\tlog.Infof(\"Internal gRPC server is running on %s:%d\", a.runtimeConfig.internalGRPCListenAddress, a.runtimeConfig.internalGRPCPort)\n\n\tif err := a.initActors(ctx); err != nil {\n\t\treturn fmt.Errorf(\"failed to initialize actors: %w\", err)\n\t}\n\n\t// MCPServers register workflow actors and must run after initActors.\n\tif err := a.loadMCPServers(ctx); err != nil {\n\t\treturn fmt.Errorf(\"failed to load mcpservers: %s\", err)\n\t}\n\tif err := a.flushOutstandingMCPServers(ctx); err != nil {\n\t\treturn err\n\t}\n\n\ta.runtimeConfig.outboundHealthz.AddTarget(\"app\").Ready()\n","sourceCodeStart":829,"sourceCodeEnd":865,"githubUrl":"https://github.com/dapr/dapr/blob/74ad41702745709bb15fe2114ff693b8c59bc3cc/pkg/runtime/runtime.go#L829-L865","documentation":"Returned when the internal gRPC server (used for sidecar-to-sidecar communication, e.g. service invocation between sidecars) fails to start via startGRPCInternalServer. The listener binds internalGRPCListenAddress:internalGRPCPort; failure is typically an address-in-use or invalid/unbindable listen address. Startup aborts.","triggerScenarios":"The internal gRPC port (--dapr-internal-grpc-port) already bound; the internal listen address set to an IP not present on the pod/host; two daprd processes sharing the same internal port.","commonSituations":"Overlapping ports when several sidecars run on one node or in one container; custom internal listen address configured in Helm/annotations that does not exist on the interface; port collisions after port-range remapping in compose files.","solutions":["Read the wrapped error to identify bind vs address error","Free or change the internal port via --dapr-internal-grpc-port so it does not collide with the API gRPC/HTTP ports","Verify internalGRPCListenAddress (defaults to loopback) is assigned to the container/host when overridden","Check the log line 'Internal gRPC server is running on ...' on a healthy run to know the expected bind target"],"exampleFix":"# before: internal port collides with API gRPC port\ndaprd --app-id myapp --dapr-internal-grpc-port 50001\n# after\ndaprd --app-id myapp --dapr-internal-grpc-port 50010","handlingStrategy":"validation","validationCode":"func checkInternalBind(addr string, port int) error {\n    ln, err := net.Listen(\"tcp\", net.JoinHostPort(addr, strconv.Itoa(port)))\n    if err != nil { return fmt.Errorf(\"internal gRPC bind %s:%d failed: %w\", addr, port, err) }\n    ln.Close()\n    return nil\n}","typeGuard":"func isInternalGRPCStartErr(err error) bool {\n    return err != nil && strings.HasPrefix(err.Error(), \"failed to start internal gRPC server:\")\n}","tryCatchPattern":null,"preventionTips":["Give the internal gRPC port its own value, never equal to the API gRPC or HTTP port","When overriding the internal listen address, verify the IP exists on the interface first","In multi-sidecar hosts/compose files, reserve a contiguous block per app"],"tags":["dapr","startup","grpc","network","port-binding","sidecar"],"backgroundTag":null,"analyzedSha":"74ad41702745709bb15fe2114ff693b8c59bc3cc","analyzedAt":"2026-08-16T04:22:26.543Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}