{"record":{"id":"d811a5ab51529180","repo":"googleapis/mcp-toolbox","slug":"toolbox-failed-to-start-listener-w-d811a5","errorCode":null,"errorMessage":"toolbox failed to start listener: %w","messagePattern":"toolbox failed to start listener: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/root.go","lineNumber":491,"sourceCode":"\tprotocol := \"http\"\n\tif useTLS {\n\t\tprotocol = \"https\"\n\t}\n\n\t// run server in background\n\tsrvErr := make(chan error)\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\tif isCustomConfigured && !opts.Cfg.DisableReload {","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/root.go#L473-L509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check for a port conflict: lsof -i :5000 or ss -ltnp, kill the stale process or change --port","Verify --cert-file/--key-file exist, are readable, and form a valid keypair","Use a non-privileged port or run with appropriate capabilities","Confirm --address is a valid interface (0.0.0.0 vs 127.0.0.1)"],"exampleFix":"// before\n./toolbox --port 5000  # address already in use\n// after\n./toolbox --port 5001","handlingStrategy":"validation","validationCode":"# pre-flight port and TLS check\nif ss -ltn | grep -q \":5000 \"; then echo \"port 5000 in use\"; exit 1; fi\nif [ -n \"$CERT_FILE\" ]; then openssl x509 -in \"$CERT_FILE\" -noout || exit 1; fi\nif [ -n \"$KEY_FILE\" ]; then openssl pkey -in \"$KEY_FILE\" -noout || exit 1; fi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check the port is free before start (or use a port manager)","Verify cert/key files exist, are readable, and match as a pair","Prefer unprivileged ports (>1024) in containers","Use 0.0.0.0 explicitly when binding in containers"],"tags":["network","tls","listener","port"],"backgroundTag":"address-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"}