gofiber/fiber · critical

failed to listen: %w

Error message

failed to listen: %w

What it means

Returned by App.Listen when createListener fails to bind the configured address. This wraps any net.Listen / tls.Listen failure (port already in use, permission denied on privileged port, invalid address, unix socket error) at the top level of Listen(). The underlying cause is preserved via %w.

Source

Thrown at listen.go:267

	}

	// Graceful shutdown
	if cfg.GracefulContext != nil {
		ctx, cancel := context.WithCancel(cfg.GracefulContext)
		defer cancel()

		go app.gracefulShutdown(ctx, &cfg)
	}

	// Start prefork
	if cfg.EnablePrefork {
		return app.prefork(addr, tlsConfig, &cfg)
	}

	// Configure Listener
	ln, err := app.createListener(addr, tlsConfig, &cfg)
	if err != nil {
		return fmt.Errorf("failed to listen: %w", err)
	}

	// Close the listener on any path that doesn't reach Serve (which otherwise
	// takes ownership of it) — an early error return or a panicking hook — so
	// the bound socket isn't leaked.
	served := false
	defer func() {
		if !served {
			_ = ln.Close() //nolint:errcheck // best-effort cleanup on the error path
		}
	}()

	// prepare the server for the start
	app.startupProcess()

	listenData := app.prepareListenData(ln.Addr().String(), getTLSConfig(ln) != nil, &cfg, nil)

	// run hooks

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Find and stop the process holding the port: lsof -i :8080 or ss -lntp.
2. Use a different port or enable SO_REUSEADDR via a custom listener.
3. Run as root/cap-net-bind-service for privileged ports, or use a non-privileged port with port forwarding.
4. For unix sockets, remove the stale socket file before listening (Fiber does this automatically, but check the parent dir).
5. Validate the address format before calling Listen.

Example fix

// before
app.Listen(":8080") // EADDRINUSE

// after
// free the port, or bind a free one:
app.Listen(":8081")

// Check the port is free before calling Listen
l, err := net.Listen("tcp", addr)
if err != nil {
    return fmt.Errorf("port check failed: %w", err)
}
l.Close()

if err := app.Listen(addr); err != nil {
    log.Errorf("listen failed: %v", err)
    // optionally retry on a different port or exit
}

When it happens

Trigger: Calling app.Listen(":8080") when port 8080 is already bound by another process; binding a privileged port (<1024) without root; an invalid address format; or a unix socket path whose parent directory doesn't exist. With TLS, tls.Listen can also fail if the TLS config is invalid.

Common situations: Another instance of the server already running on the same port, a leftover process, Docker port collision, binding :80/:443 as a non-root user, or a stale unix socket file.

Related errors

• file: failed to store file: %q to %q: %w
• tls: cannot load TLS key pair from certFile=%q and keyFile=%
• failed to read client CA file %q: %w
• unexpected error when trying to remove unix socket file %q:
• prefork: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/b0aee3579d52d271.json. Report an issue: GitHub.