{"record":{"id":"04d38ac674780061","repo":"googleapis/mcp-toolbox","slug":"unable-to-initialize-server-w","errorCode":null,"errorMessage":"unable to initialize server: %w","messagePattern":"unable to initialize server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/server/server.go","lineNumber":491,"sourceCode":"\taddr := net.JoinHostPort(cfg.Address, strconv.Itoa(cfg.Port))\n\tsrv := &http.Server{Addr: addr, Handler: r}\n\n\tsseManager := newSseManager(ctx)\n\n\tprimitiveManager := primitives.NewPrimitiveManager(sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, promptsMap, groupsMap)\n\n\tlimit := cfg.HttpMaxRequestBytes\n\tif limit <= 0 {\n\t\tlimit = DefaultHTTPMaxRequestBytes\n\t}\n\n\tmcp.InitializeProtocols(mcp.ProtocolOptions{\n\t\tDisableExt: cfg.DisableExt,\n\t})\n\n\tprmURLStr, err := parsePRMURL(cfg.ToolboxUrl)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to initialize server: %w\", err)\n\t}\n\tprmURL, err := url.Parse(prmURLStr)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to initialize server: %w\", err)\n\t}\n\n\ts := &Server{\n\t\tversion:             cfg.Version,\n\t\tsqlCommenterEnabled: cfg.SQLCommenter,\n\t\tsrv:                 srv,\n\t\troot:                r,\n\t\tlogger:              l,\n\t\tinstrumentation:     instrumentation,\n\t\tsseManager:          sseManager,\n\t\tPrimitiveMgr:        primitiveManager,\n\t\ttoolboxUrl:          cfg.ToolboxUrl,\n\t\tprmURL:              prmURLStr,\n\t\tmcpPrmFile:          cfg.McpPrmFile,","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/server.go#L473-L509","documentation":"NewServer calls parsePRMURL(cfg.ToolboxUrl) to compute the URL advertised in WWW-Authenticate Protected Resource Metadata headers. If cfg.ToolboxUrl is set but cannot be converted into a valid PRM URL (malformed scheme/host), the server refuses to start, wrapping the parse error under this message.","triggerScenarios":"Setting --toolbox-url (or cfg.ToolboxUrl) to a value that parsePRMURL (internal/server/prm.go) rejects — e.g. missing scheme, empty string where required, or a URL with no host — during NewServer.","commonSituations":"Deployments behind proxies configuring toolbox-url as \"my-proxy.example.com\" without \"https://\", or leftover placeholder values like \"changeme\" in Helm/K8s manifests.","solutions":["Set --toolbox-url to a fully qualified URL including scheme, e.g. https://toolbox.example.com.","If OAuth/PRM advertisement is not needed, unset toolbox-url entirely instead of passing a placeholder.","Check for stripped scheme in env-var templating (e.g. ${TOOLBOX_URL} missing its https:// prefix)."],"exampleFix":"// before\ntoolbox serve --toolbox-url toolbox.internal:5000 ...\n\n// after\ntoolbox serve --toolbox-url https://toolbox.internal:5000 ...","handlingStrategy":"validation","validationCode":"u, err := url.Parse(cfg.ToolboxUrl)\nif err != nil || u.Scheme == \"\" || u.Host == \"\" {\n    return fmt.Errorf(\"--toolbox-url must be an absolute URL like https://host:port, got %q\", cfg.ToolboxUrl)\n}","typeGuard":"func isAbsoluteURL(s string) bool {\n    u, err := url.Parse(s)\n    return err == nil && u.Scheme != \"\" && u.Host != \"\"\n}","tryCatchPattern":"if _, err := server.NewServer(ctx, cfg); err != nil {\n    if strings.Contains(err.Error(), \"unable to initialize server\") && !isAbsoluteURL(cfg.ToolboxUrl) {\n        cfg.ToolboxUrl = \"https://\" + cfg.ToolboxUrl\n        _, err = server.NewServer(ctx, cfg)\n    }\n    return err\n}","preventionTips":["Always include the scheme (https://) in toolbox-url values.","Validate TOOLBOX_URL with url.Parse in entrypoint scripts before exec.","Avoid placeholder values like 'changeme' in Helm values files; fail fast with an enum/required check."],"tags":["go","url","oauth","configuration"],"backgroundTag":"invalid-url","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"}