googleapis/mcp-toolbox · error

unable to initialize source %q: %w

Error message

unable to initialize source %q: %w

What it means

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.

Source

Thrown at internal/sources/connect.go:203

		// request that paid for it.
		base := trace.ContextWithSpanContext(
			context.WithoutCancel(c.startupCtx),
			trace.SpanContextFromContext(ctx),
		)
		connectCtx, cancel := context.WithTimeout(base, c.timeout)
		defer cancel()

		// What is deferred is the connection, not the source, which is built
		// at startup either way and keeps server.go's init span. Emitting the
		// connect span from here is what lets a source drop its own: every
		// connect reaches this path, whether it runs at startup or later.
		childCtx, span := InitConnectionSpan(connectCtx, c.tracer, c.sourceType, c.name)
		defer span.End()

		value, err := connect(childCtx)
		if err != nil {
			span.SetStatus(codes.Error, err.Error())
			return nil, fmt.Errorf("unable to initialize source %q: %w", c.name, err)
		}

		c.mu.Lock()
		if c.closed {
			c.mu.Unlock()
			// Close ran while this attempt was in flight. Nothing will hand the
			// value out, so it is released here rather than left to outlive the
			// holder. The connect context is already near its deadline and the
			// caller's is irrelevant to a teardown, so neither bounds the close.
			if cerr := c.release(context.WithoutCancel(childCtx), value); cerr != nil {
				return nil, fmt.Errorf("unable to close source %q: %w", c.name, cerr)
			}
			return nil, fmt.Errorf("unable to initialize source %q: source is closed", c.name)
		}
		c.value, c.ready = value, true
		c.mu.Unlock()
		return value, nil
	})

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped cause (%w) for the real driver error and fix that root cause
2. Validate connection config (host, port, user, password, SSL mode) against the database
3. Test connectivity from the toolbox host (nc/ping to the DB endpoint)
4. Check tracing spans (InitConnectionSpan) for where the connect attempt stalled or failed

Example fix

// before
kind: source
name: my-pg
type: postgres
password: wrong-password
// after
kind: source
name: my-pg
type: postgres
password: correct-password-from-secret

// Validate DB connectivity before wiring the source
nc, err := net.DialTimeout("tcp", "db-host:5432", 5*time.Second)
if err != nil {
	log.Fatalf("DB host unreachable: %v", err)
}
nc.Close()
// Also verify credentials with a throwaway connection/ping

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• toolbox failed to initialize: %w
• unable to create pool: %w
• unable to create session: %v
• sql.Open: %w
• unable to create db connection: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/e5dcc4bf25b04066. Report an issue: GitHub.