{"record":{"id":"e5dcc4bf25b04066","repo":"googleapis/mcp-toolbox","slug":"unable-to-initialize-source-q-w-e5dcc4","errorCode":null,"errorMessage":"unable to initialize source %q: %w","messagePattern":"unable to initialize source %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/connect.go","lineNumber":203,"sourceCode":"\t\t// request that paid for it.\n\t\tbase := trace.ContextWithSpanContext(\n\t\t\tcontext.WithoutCancel(c.startupCtx),\n\t\t\ttrace.SpanContextFromContext(ctx),\n\t\t)\n\t\tconnectCtx, cancel := context.WithTimeout(base, c.timeout)\n\t\tdefer cancel()\n\n\t\t// What is deferred is the connection, not the source, which is built\n\t\t// at startup either way and keeps server.go's init span. Emitting the\n\t\t// connect span from here is what lets a source drop its own: every\n\t\t// connect reaches this path, whether it runs at startup or later.\n\t\tchildCtx, span := InitConnectionSpan(connectCtx, c.tracer, c.sourceType, c.name)\n\t\tdefer span.End()\n\n\t\tvalue, err := connect(childCtx)\n\t\tif err != nil {\n\t\t\tspan.SetStatus(codes.Error, err.Error())\n\t\t\treturn nil, fmt.Errorf(\"unable to initialize source %q: %w\", c.name, err)\n\t\t}\n\n\t\tc.mu.Lock()\n\t\tif c.closed {\n\t\t\tc.mu.Unlock()\n\t\t\t// Close ran while this attempt was in flight. Nothing will hand the\n\t\t\t// value out, so it is released here rather than left to outlive the\n\t\t\t// holder. The connect context is already near its deadline and the\n\t\t\t// caller's is irrelevant to a teardown, so neither bounds the close.\n\t\t\tif cerr := c.release(context.WithoutCancel(childCtx), value); cerr != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"unable to close source %q: %w\", c.name, cerr)\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"unable to initialize source %q: source is closed\", c.name)\n\t\t}\n\t\tc.value, c.ready = value, true\n\t\tc.mu.Unlock()\n\t\treturn value, nil\n\t})","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/connect.go#L185-L221","documentation":"Returned when the underlying connect function passed to ConnectOnce.Do fails. The library wraps any error from connect(childCtx) as 'unable to initialize source %q: %w' after marking the tracing span as errored. The wrapped cause is the actual database/driver connection error.","triggerScenarios":"The connect callback (e.g., creating a pgx pool, opening a driver connection) returns an error: unreachable host, bad credentials, TLS handshake failure, timeout on the startup context, or driver misconfiguration.","commonSituations":"Wrong DSN/connection config, database firewall blocking the toolbox host, expired credentials or IAM auth issues, TLS cert problems, or the database being temporarily unavailable at first use.","solutions":["Read the wrapped cause (%w) for the real driver error and fix that root cause","Validate connection config (host, port, user, password, SSL mode) against the database","Test connectivity from the toolbox host (nc/ping to the DB endpoint)","Check tracing spans (InitConnectionSpan) for where the connect attempt stalled or failed"],"exampleFix":"// before\nkind: source\nname: my-pg\ntype: postgres\npassword: wrong-password\n// after\nkind: source\nname: my-pg\ntype: postgres\npassword: correct-password-from-secret","handlingStrategy":"validation","validationCode":"// Validate DB connectivity before wiring the source\nnc, err := net.DialTimeout(\"tcp\", \"db-host:5432\", 5*time.Second)\nif err != nil {\n\tlog.Fatalf(\"DB host unreachable: %v\", err)\n}\nnc.Close()\n// Also verify credentials with a throwaway connection/ping","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate all connection parameters at deploy time with a smoke-test connect","Keep tracing enabled to see which connect phase fails","Rotate credentials without downtime and verify secrets are current","Add readiness checks that ping the DB before serving traffic"],"tags":["initialization","connection","database","tracing"],"backgroundTag":"source-initialization-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"}