{"record":{"id":"eda9b60b485f9b49","repo":"kopia/kopia","slug":"listen-error","errorCode":null,"errorMessage":"listen error","messagePattern":"listen error","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command_server_tls.go","lineNumber":58,"sourceCode":"\tvar l net.Listener\n\n\tvar err error\n\n\tlisteners, err := activation.Listeners()\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"socket-activation error\")\n\t}\n\n\tswitch len(listeners) {\n\tcase 0:\n\t\tif after, ok := strings.CutPrefix(httpServer.Addr, \"unix:\"); ok {\n\t\t\tl, err = (&net.ListenConfig{}).Listen(ctx, \"unix\", after)\n\t\t} else {\n\t\t\tl, err = (&net.ListenConfig{}).Listen(ctx, \"tcp\", httpServer.Addr)\n\t\t}\n\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"listen error\")\n\t\t}\n\tcase 1:\n\t\tl = listeners[0]\n\tdefault:\n\t\treturn errors.Errorf(\"Too many activated sockets found.  Expected 1, got %v\", len(listeners))\n\t}\n\n\tif err := insecureserverbind.ValidateListenerAddrIfRestricted(\n\t\tc.serverStartInsecure,\n\t\tc.serverStartWithoutPassword,\n\t\tc.serverStartAllowDangerousUnauthenticatedNetwork,\n\t\tl.Addr(),\n\t); err != nil {\n\t\tl.Close() //nolint:errcheck\n\n\t\treturn errors.Wrap(err, \"insecure server bind validation\")\n\t}\n","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/cli/command_server_tls.go#L40-L76","documentation":"Kopia's startServerWithOptionalTLS wraps any net.ListenConfig.Listen failure with 'listen error'. This means the process could not bind the HTTP server to the configured TCP address (httpServer.Addr) or Unix socket, so the server never starts. It is a transport-level failure before any TLS or request handling happens.","triggerScenarios":"Calling `kopia server start` (via run -> startServerWithOptionalTLS) when the configured --address host:port is already bound by another process, the port is privileged without root, the interface/hostname does not resolve, or the Unix socket path is not writable.","commonSituations":"Port already in use by a stale Kopia instance; running on a privileged port (<1024) as non-root; --address with a hostname that resolves to an IP not on the machine; read-only filesystem for the Unix socket directory.","solutions":["Free the port or socket path (check with `lsof -i :<port>` or `ss -ltnp`) and stop the conflicting process, or pick another --address","Use an unprivileged port (>=1024) or run with sufficient privileges/capabilities (CAP_NET_BIND_SERVICE)","Verify the host in --address resolves to a local interface; use 127.0.0.1 or 0.0.0.0 if unsure","Ensure the parent directory of a Unix socket path exists and is writable"],"exampleFix":"// before\nkopia server start --address 0.0.0.0:443\n// after\nkopia server start --address 127.0.0.1:51515","handlingStrategy":"validation","validationCode":"func isPortFree(addr string) bool {\n    ln, err := net.Listen(\"tcp\", addr)\n    if err != nil { return false }\n    ln.Close()\n    return true\n}\n// call before `kopia server start --address <addr>`","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check port availability with ss/lsof before starting","Always run the server on an unprivileged port","Use systemd socket activation to avoid bind races","Verify hostname resolution for --address targets"],"tags":["network","bind","server-startup"],"backgroundTag":"address-already-in-use","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}