kopia/kopia · error
listen error
Error message
listen error
What it means
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.
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
Example fix
// before kopia server start --address 0.0.0.0:443 // after kopia server start --address 127.0.0.1:51515
Defensive patterns
Strategy: validation
Validate before calling
func isPortFree(addr string) bool {
ln, err := net.Listen("tcp", addr)
if err != nil { return false }
ln.Close()
return true
}
// call before `kopia server start --address <addr>` Prevention
- 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
When it happens
Trigger: 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.
Common situations: 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.
Related errors
AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07).
Data as JSON: /api/errors/eda9b60b485f9b49.
Report an issue: GitHub.
Appendix: source
Thrown at cli/command_server_tls.go:58
var l net.Listener
var err error
listeners, err := activation.Listeners()
if err != nil {
return errors.Wrap(err, "socket-activation error")
}
switch len(listeners) {
case 0:
if after, ok := strings.CutPrefix(httpServer.Addr, "unix:"); ok {
l, err = (&net.ListenConfig{}).Listen(ctx, "unix", after)
} else {
l, err = (&net.ListenConfig{}).Listen(ctx, "tcp", httpServer.Addr)
}
if err != nil {
return errors.Wrap(err, "listen error")
}
case 1:
l = listeners[0]
default:
return errors.Errorf("Too many activated sockets found. Expected 1, got %v", len(listeners))
}
if err := insecureserverbind.ValidateListenerAddrIfRestricted(
c.serverStartInsecure,
c.serverStartWithoutPassword,
c.serverStartAllowDangerousUnauthenticatedNetwork,
l.Addr(),
); err != nil {
l.Close() //nolint:errcheck
return errors.Wrap(err, "insecure server bind validation")
}
View on GitHub (pinned to 82495e54b5)