{"record":{"id":"b6afe2530f6b50e2","repo":"ory/hydra","slug":"could-not-start-debug-server-on-port-d-w","errorCode":null,"errorMessage":"could not start debug server on port %d: %w","messagePattern":"could not start debug server on port (.+?): %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cmd_perform_device_flow.go","lineNumber":46,"sourceCode":")\n\nfunc NewPerformDeviceCodeCmd() *cobra.Command {\n\tcmd := &cobra.Command{\n\t\tUse:     \"device-code\",\n\t\tExample: \"{{ .CommandPath }} --client-id ...\",\n\t\tShort:   \"Example OAuth 2.0 Client performing the OAuth 2.0 Device Code Flow\",\n\t\tLong: `Performs the device code flow. Useful for getting an access token and an ID token in machines without a browser.\nThe client that will be used MUST use the \"none\" or \"client_secret_post\" token-endpoint-auth-method.`,\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tclient, endpoint, err := cliclient.NewClient(cmd)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\n\t\t\tif port := flagx.MustGetInt(cmd, \"port\"); port >= 0 {\n\t\t\t\tlistener, err := net.Listen(\"tcp\", fmt.Sprintf(\"127.0.0.1:%d\", port))\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"could not start debug server on port %d: %w\", port, err)\n\t\t\t\t}\n\t\t\t\tsrv := http.Server{Handler: newDeviceSrv(client)}\n\t\t\t\tgo func() {\n\t\t\t\t\tif err := srv.Serve(listener); err != nil && err != http.ErrServerClosed {\n\t\t\t\t\t\t_, _ = fmt.Fprintf(cmd.ErrOrStderr(), \"Debug server error: %v\\n\", err)\n\t\t\t\t\t}\n\t\t\t\t}()\n\t\t\t\tdefer srv.Close() //nolint:errcheck\n\t\t\t}\n\n\t\t\tendpoint = cliclient.GetOAuth2URLOverride(cmd, endpoint)\n\n\t\t\tctx := context.WithValue(cmd.Context(), oauth2.HTTPClient, client)\n\t\t\tscopes := flagx.MustGetStringSlice(cmd, \"scope\")\n\t\t\tdeviceAuthUrl := flagx.MustGetString(cmd, \"device-auth-url\")\n\t\t\ttokenUrl := flagx.MustGetString(cmd, \"token-url\")\n\t\t\taudience := flagx.MustGetStringSlice(cmd, \"audience\")\n","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/cmd/cmd_perform_device_flow.go#L28-L64","documentation":"The perform device flow command in cmd/cmd_perform_device_flow.go starts a local debug HTTP server; this error is returned when net.Listen on 127.0.0.1:<port> fails. It wraps the underlying OS error (typically address already in use or permission denied).","triggerScenarios":"Running `hydra perform device flow --port N` where port N is already bound by another process, or N is a privileged port (<1024) without permissions, or the loopback interface is unavailable.","commonSituations":"Previous debug server instance still running and holding the port, another dev service (webpack, vite) on the same port, running with --port 80 in a non-root container.","solutions":["Pick a different free port, e.g. --port 4446","Find and stop the process holding the port: lsof -i :<port> or ss -ltnp","Use a port >= 1024 if running unprivileged","Check that 127.0.0.1 loopback is available (containers/network namespaces)"],"exampleFix":"// before\nhydra perform device flow --port 8080\n// after\nhydra perform device flow --port 8081  # 8080 was occupied","handlingStrategy":"validation","validationCode":"port := flagx.MustGetInt(cmd, \"port\")\nif ln, err := net.Listen(\"tcp\", fmt.Sprintf(\"127.0.0.1:%d\", port)); err != nil {\n    return fmt.Errorf(\"port %d unavailable: %w\", port, err)\n} else { ln.Close() }","typeGuard":null,"tryCatchPattern":"if err != nil {\n    fmt.Fprintf(os.Stderr, \"port %d busy (%v): stop the other process or pick another port\\n\", port, err)\n    os.Exit(1)\n}","preventionTips":["Reserve debug ports per developer/tool","Add pre-flight port checks in scripts","Use ephemeral high ports"],"tags":["network","port-binding","cli"],"backgroundTag":"address-already-in-use","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}