{"record":{"id":"c312baac869b2d02","repo":"googleapis/mcp-toolbox","slug":"toolbox-failed-to-initialize-w-c312ba","errorCode":null,"errorMessage":"toolbox failed to initialize: %w","messagePattern":"toolbox failed to initialize: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/root.go","lineNumber":467,"sourceCode":"\t\tif opts.Cfg.EnableAPI {\n\t\t\terrMsg := fmt.Errorf(\"MCP Auth cannot be enabled together with the legacy HTTP API (--enable-api)\")\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t\tif opts.Cfg.ToolboxUrl == \"\" {\n\t\t\topts.Cfg.ToolboxUrl = os.Getenv(\"TOOLBOX_URL\")\n\t\t}\n\t\tif opts.Cfg.ToolboxUrl == \"\" {\n\t\t\terrMsg := fmt.Errorf(\"MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable\")\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t}\n\n\t// start server\n\ts, err := server.NewServer(ctx, opts.Cfg)\n\tif err != nil {\n\t\terrMsg := fmt.Errorf(\"toolbox failed to initialize: %w\", err)\n\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\treturn errMsg\n\t}\n\n\tuseTLS := opts.Cfg.CertFile != \"\" || opts.Cfg.KeyFile != \"\"\n\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","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/root.go#L449-L485","documentation":"server.NewServer builds the toolbox server from the resolved config (loading tools files, initializing sources, validating auth services). Any failure there is wrapped with 'toolbox failed to initialize' and logged, so the exact cause is in the wrapped %w error on the next line of the log.","triggerScenarios":"Invalid tools.yaml / prebuilt config, a source failing to initialize (bad credentials, unreachable database), or an invalid auth service config passed into server.NewServer.","commonSituations":"Malformed YAML, wrong connection strings/secrets, unsupported tool kind, invalid auth configuration, missing required fields in a source config.","solutions":["Read the wrapped '%w' cause line in the log for the underlying error","Validate tools.yaml syntax and source credentials","Run with debug logging to see which source/tool/auth failed","Test database connectivity separately (e.g. psql/mysql client)"],"exampleFix":"// before\ntools.yaml: sources:\n  my-pg:\n    kind: postgres\n    uri: ${DB_URI}  # env var unset -> empty uri\n// after\nexport DB_URI=postgres://user:pass@host:5432/db","handlingStrategy":"try-catch","validationCode":"# validate config before launch\ngo run . --tools-file tools.yaml --dry-run 2>&1 || echo 'toolbox config invalid'\n# and check env interpolation\nenv | grep -E 'DB_|API_KEY' >/dev/null || echo 'missing source env vars'","typeGuard":null,"tryCatchPattern":"// wrapper around launching toolbox\nout, err := exec.CommandContext(ctx, \"./toolbox\", args...).CombinedOutput()\nif err != nil && strings.Contains(string(out), \"toolbox failed to initialize\") {\n    // parse the wrapped '%w' cause line and fix tools.yaml/sources\n    log.Fatalf(\"toolbox init failed: %s\", out)\n}","preventionTips":["Validate tools.yaml with a YAML linter before deploy","Secret-check: ensure referenced env vars exist in the runtime environment","Test source connectivity in CI before rolling out","Pin and test configs in staging first"],"tags":["initialization","server","configuration"],"backgroundTag":"server-init-failed","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"}