{"record":{"id":"061769940642da39","repo":"googleapis/mcp-toolbox","slug":"toolbox-failed-to-start-listener-w","errorCode":null,"errorMessage":"toolbox failed to start listener: %w","messagePattern":"toolbox failed to start listener: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/internal/serve/command.go","lineNumber":101,"sourceCode":"\tprotocol := \"http\"\n\tif useTLS {\n\t\tprotocol = \"https\"\n\t}\n\n\t// run server in background\n\tsrvErr := make(chan error, 1)\n\tif opts.Cfg.Stdio {\n\t\tgo func() {\n\t\t\tdefer close(srvErr)\n\t\t\terr = s.ServeStdio(ctx, opts.IOStreams.In, opts.IOStreams.Out)\n\t\t\tif err != nil {\n\t\t\t\tsrvErr <- err\n\t\t\t}\n\t\t}()\n\t} else {\n\t\terr = s.Listen(ctx, opts.Cfg.CertFile, opts.Cfg.KeyFile)\n\t\tif err != nil {\n\t\t\terrMsg := fmt.Errorf(\"toolbox failed to start listener: %w\", err)\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t\topts.Logger.InfoContext(ctx, \"Server ready to serve!\")\n\t\tif opts.Cfg.UI {\n\t\t\topts.Logger.InfoContext(ctx, fmt.Sprintf(\"Toolbox UI is up and running at: %s://%s:%d/ui\", protocol, opts.Cfg.Address, opts.Cfg.Port))\n\t\t}\n\n\t\tgo func() {\n\t\t\tdefer close(srvErr)\n\t\t\terr = s.Serve(ctx)\n\t\t\tif err != nil {\n\t\t\t\tsrvErr <- err\n\t\t\t}\n\t\t}()\n\t}\n\n\t// wait for either the server to error out or the command's context to be canceled","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/internal/serve/command.go#L83-L119","documentation":"In runServe's non-TLS path, the server calls s.Listen(ctx, certFile, keyFile) to bind the address and serve. If the listener cannot start (port in use, permission denied, bad address), the error is wrapped with this message.","triggerScenarios":"s.Listen returns an error: the configured address:port is already bound, the port is privileged (<1024) without permissions, or the address is invalid/unavailable.","commonSituations":"Another toolbox instance or service already listening on 5000 (the default port), running in a container without port mapping, or binding to an interface that doesn't exist.","solutions":["Check for a process already bound to the port (lsof -i :5000) and stop it or change --port","Choose an unprivileged port (>1024) if not running as root","Verify the --address value resolves to a valid local interface","Check container/K8s port mappings and security policies"],"exampleFix":"// before\n./toolbox serve --port 80  // privileged\n// after\n./toolbox serve --port 5000","handlingStrategy":"validation","validationCode":"// check the port is free before launching\nif l, err := net.Listen(\"tcp\", \":5000\"); err != nil {\n    log.Fatal(\"port 5000 already in use\")\n} else { l.Close() }","typeGuard":null,"tryCatchPattern":"err = s.Listen(ctx, cfg.CertFile, cfg.KeyFile)\nif err != nil {\n    return fmt.Errorf(\"toolbox failed to start listener: %w\", err)\n}","preventionTips":["Pick ports >1024 and make them configurable per environment","Check for stale processes holding the port before restart","Verify container port mappings and host networking settings"],"tags":["network","server","port-binding","listen"],"backgroundTag":"address-already-in-use","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}