{"record":{"id":"b705591b95dc9eab","repo":"dapr/dapr","slug":"failed-to-start-api-grpc-server-w","errorCode":null,"errorMessage":"failed to start API gRPC server: %w","messagePattern":"failed to start API gRPC server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/runtime/runtime.go","lineNumber":821,"sourceCode":"\tif err = a.loadWorkflowAccessPolicies(ctx); err != nil {\n\t\treturn fmt.Errorf(\"failed to load workflow access policies: %w\", err)\n\t}\n\n\ta.reloader.SetPolicyRecompiler(reconciler.WorkflowAccessPolicyOptions{\n\t\tAppID:      a.runtimeConfig.id,\n\t\tLoader:     a.reloader.Loader(),\n\t\tCompStore:  a.compStore,\n\t\tRecompiler: a.workflowAccessPolicies.Store,\n\t\tHealthz:    a.runtimeConfig.healthz,\n\t})\n\n\tif err = a.runnerCloser.AddCloser(a.daprGRPCAPI); err != nil {\n\t\treturn err\n\t}\n\n\terr = a.startGRPCAPIServer(ctx, a.daprGRPCAPI, a.runtimeConfig.apiGRPCPort)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to start API gRPC server: %w\", err)\n\t}\n\n\tif a.runtimeConfig.unixDomainSocket != \"\" {\n\t\tlog.Info(\"API gRPC server is running on a Unix Domain Socket\")\n\t} else {\n\t\tlog.Infof(\"API gRPC server is running on port %v\", a.runtimeConfig.apiGRPCPort)\n\t}\n\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)","sourceCodeStart":803,"sourceCodeEnd":839,"githubUrl":"https://github.com/dapr/dapr/blob/74ad41702745709bb15fe2114ff693b8c59bc3cc/pkg/runtime/runtime.go#L803-L839","documentation":"Returned when DaprRuntime.Run cannot start the public API gRPC server (startGRPCAPIServer). The underlying failure is almost always the net.Listen on the API gRPC port (default 50001) or, when --unix-domain-socket is set, creating the gRPC Unix domain socket file. The error wraps the OS-level cause; startup aborts.","triggerScenarios":"Another process already bound the API gRPC port; --dapr-grpc-port set to a privileged port (<1024) while running unprivileged; Unix domain socket directory missing, read-only, or lacking write permission; port already taken by a second daprd instance for the same app-id.","commonSituations":"Two sidecars (or a leftover daprd) on the same host using default port 50001; container with a read-only volume mounted as the UDS dir; SELinux/AppArmor denying socket creation; Docker port-map collision.","solutions":["Inspect the wrapped error: 'address already in use' means a port conflict, 'permission denied' means privileged port or UDS dir perms","Free the conflicting port (lsof -i :50001) or set a different one via --dapr-grpc-port","If using --unix-domain-socket, ensure the directory exists, is writable by the daprd user, and is on a filesystem that supports UDS (not NFS/overlay quirks)","Ensure only one daprd runs per app-id/port pair"],"exampleFix":"# before\ndaprd --app-id myapp --dapr-grpc-port 50001\n# after (port 50001 taken by another process)\ndaprd --app-id myapp --dapr-grpc-port 50101","handlingStrategy":"validation","validationCode":"// Pre-flight: is the API gRPC port bindable?\nfunc checkPortFree(port int) error {\n    ln, err := net.Listen(\"tcp\", fmt.Sprintf(\"0.0.0.0:%d\", port))\n    if err != nil { return fmt.Errorf(\"gRPC API port %d unavailable: %w\", port, err) }\n    ln.Close()\n    return nil\n}","typeGuard":"func isAddrInUse(err error) bool {\n    var opErr *net.OpError\n    if errors.As(err, &opErr) {\n        return errors.Is(opErr.Err, syscall.EADDRINUSE)\n    }\n    return false\n}","tryCatchPattern":null,"preventionTips":["Assign one distinct port triple (http, grpc, internal-grpc) per sidecar on shared hosts","When embedding the runtime, probe the ports with net.Listen before constructing DaprRuntime","For UDS deployments, mount an emptyDir at the socket dir and verify write access in an initContainer"],"tags":["dapr","startup","grpc","network","port-binding"],"backgroundTag":null,"analyzedSha":"74ad41702745709bb15fe2114ff693b8c59bc3cc","analyzedAt":"2026-08-16T04:22:26.543Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}