googleapis/mcp-toolbox · error

toolbox failed to start listener: %w

Error message

toolbox failed to start listener: %w

What it means

After creating the server, toolbox calls s.Listen (with optional TLS cert/key) to bind the configured address/port. If Listen returns an error (port already in use, permission denied, bad TLS cert/key files), it is wrapped as 'toolbox failed to start listener' and run() exits.

Source

Thrown at cmd/root.go:491

	protocol := "http"
	if useTLS {
		protocol = "https"
	}

	// run server in background
	srvErr := make(chan error)
	if opts.Cfg.Stdio {
		go func() {
			defer close(srvErr)
			err = s.ServeStdio(ctx, opts.IOStreams.In, opts.IOStreams.Out)
			if err != nil {
				srvErr <- err
			}
		}()
	} else {
		err = s.Listen(ctx, opts.Cfg.CertFile, opts.Cfg.KeyFile)
		if err != nil {
			errMsg := fmt.Errorf("toolbox failed to start listener: %w", err)
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
		opts.Logger.InfoContext(ctx, "Server ready to serve!")
		if opts.Cfg.UI {
			opts.Logger.InfoContext(ctx, fmt.Sprintf("Toolbox UI is up and running at: %s://%s:%d/ui", protocol, opts.Cfg.Address, opts.Cfg.Port))
		}

		go func() {
			defer close(srvErr)
			err = s.Serve(ctx)
			if err != nil {
				srvErr <- err
			}
		}()
	}

	if isCustomConfigured && !opts.Cfg.DisableReload {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check for a port conflict: lsof -i :5000 or ss -ltnp, kill the stale process or change --port
2. Verify --cert-file/--key-file exist, are readable, and form a valid keypair
3. Use a non-privileged port or run with appropriate capabilities
4. Confirm --address is a valid interface (0.0.0.0 vs 127.0.0.1)

Example fix

// before
./toolbox --port 5000  # address already in use
// after
./toolbox --port 5001

# pre-flight port and TLS check
if ss -ltn | grep -q ":5000 "; then echo "port 5000 in use"; exit 1; fi
if [ -n "$CERT_FILE" ]; then openssl x509 -in "$CERT_FILE" -noout || exit 1; fi
if [ -n "$KEY_FILE" ]; then openssl pkey -in "$KEY_FILE" -noout || exit 1; fi

When it happens

Trigger: Another process is already bound to --address/--port; binding a privileged port (<1024) without privileges; --cert-file/--key-file pointing to missing/invalid/corrupt files; invalid address.

Common situations: Port 5000 already used by a previous toolbox instance or another dev server; stale container holding the port; TLS cert paths wrong after a config move.

Related errors

• unable to connect successfully: %w
• unable to connect successfully: %w
• toolbox failed to start listener: %w
• failed to discover OIDC config: %w
• failed to fetch OIDC config: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/d811a5ab51529180. Report an issue: GitHub.