{"record":{"id":"d3e7a522076351df","repo":"dapr/dapr","slug":"failed-to-get-free-port-for-internal-grpc-server","errorCode":null,"errorMessage":"failed to get free port for internal grpc server: %w","messagePattern":"failed to get free port for internal grpc server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/runtime/config.go","lineNumber":437,"sourceCode":"\n\tintc.profilePort, err = strconv.Atoi(c.ProfilePort)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error parsing profile-port flag: %w\", err)\n\t}\n\n\tif c.DaprInternalGRPCPort != \"\" && c.DaprInternalGRPCPort != \"0\" {\n\t\tintc.internalGRPCPort, err = strconv.Atoi(c.DaprInternalGRPCPort)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error parsing dapr-internal-grpc-port: %w\", err)\n\t\t}\n\t} else {\n\t\t// Get a \"stable random\" port in the range 47300-49,347 if it can be\n\t\t// acquired using a deterministic algorithm that returns the same value if\n\t\t// the same app is restarted\n\t\t// Otherwise, the port will be random.\n\t\tintc.internalGRPCPort, err = ports.GetStablePort(47300, intc.id)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to get free port for internal grpc server: %w\", err)\n\t\t}\n\t}\n\n\tif c.DaprPublicPort != \"\" {\n\t\tvar port int\n\n\t\tport, err = strconv.Atoi(c.DaprPublicPort)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error parsing dapr-public-port: %w\", err)\n\t\t}\n\n\t\tintc.publicPort = &port\n\t}\n\n\tif c.ApplicationPort != \"\" {\n\t\tintc.appConnectionConfig.Port, err = strconv.Atoi(c.ApplicationPort)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error parsing app-port: %w\", err)","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/dapr/dapr/blob/74ad41702745709bb15fe2114ff693b8c59bc3cc/pkg/runtime/config.go#L419-L455","documentation":"ports.GetStablePort failed while allocating the internal gRPC port (pkg/runtime/config.go:437). When --dapr-internal-grpc-port is unset or \"0\", Dapr derives a deterministic port in the 47300-49347 range from the app ID so restarts reuse it; this error means that derivation/acquisition failed. The wrapped error carries the exact cause.","triggerScenarios":"Calling daprd without --dapr-internal-grpc-port where GetStablePort(47300, appID) errors — e.g. an appID that the deterministic algorithm rejects, or an environment failure inside the port helper.","commonSituations":"Sidecars launched with unusual/empty app IDs in custom hosts; embedders constructing runtime configs programmatically without a valid id; rare platform errors surfaced by the helper.","solutions":["Set --dapr-internal-grpc-port explicitly to a known-free port (e.g. 50002) to bypass stable-port derivation entirely","Inspect the wrapped error to see the exact failure inside GetStablePort","Verify the app ID (--app-id / id field) is a non-empty sane value"],"exampleFix":"# before\ndaprd --app-id myapp   # relies on GetStablePort, fails\n\n# after\ndaprd --app-id myapp --dapr-internal-grpc-port 50002","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin --dapr-internal-grpc-port to a known-free port in orchestration instead of relying on stable-port derivation","Keep --app-id non-empty and stable so deterministic port derivation has sane input","Treat any GetStablePort failure as actionable: read the wrapped error before retrying"],"tags":["go","dapr","ports","internal-api","startup"],"backgroundTag":null,"analyzedSha":"74ad41702745709bb15fe2114ff693b8c59bc3cc","analyzedAt":"2026-08-16T04:22:26.543Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}