googleapis/mcp-toolbox · critical

unable to create Oracle connection: %w

Error message

unable to create Oracle connection: %w

What it means

This error is returned by the oracle Config.Initialize method when initOracleConnection fails while creating the database/sql handle. It wraps the underlying driver error (from sql.Open or connect-string construction) so the root cause (bad driver name, malformed connection string, missing driver registration) is preserved. It means no connection object could even be created — distinct from a successful open followed by a failed ping (error 901).

Source

Thrown at internal/sources/oracle/oracle.go:106

	if hasTnsAdmin && !c.UseOCI {
		return fmt.Errorf("`tnsAdmin` can only be used when `UseOCI` is true, or use `walletLocation` instead")
	}

	if hasWallet && c.UseOCI {
		return fmt.Errorf("when using an OCI driver, use `tnsAdmin` to specify credentials file location instead")
	}

	return nil
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	db, err := initOracleConnection(ctx, tracer, r)
	if err != nil {
		return nil, fmt.Errorf("unable to create Oracle connection: %w", err)
	}

	err = db.PingContext(ctx)
	if err != nil {
		db.Close()
		return nil, fmt.Errorf("unable to connect to Oracle successfully: %w", err)
	}

	s := &Source{
		Config: r,
		DB:     db,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check the wrapped cause (%w) in the error message for the driver-specific failure reason.
2. Verify the connection method in your YAML: exactly one of tnsAlias, connectionString, or host+serviceName, with correct host/port/serviceName values.
3. URL-encode special characters in user/password, or percent-encode them in config (the source decodes percent-encoded values).
4. If useOCI: true, ensure Oracle Instant Client libraries are installed and visible (LD_LIBRARY_PATH); otherwise omit useOCI to use the pure-Go go-ora driver.
5. Enable debug logging to see the exact serverString/driver used and compare with a working sqlplus/SQLcl connection.

Example fix

// before (special chars break the oracle:// URL)
user: "scott"
password: "p@ss:word"
// after (percent-encode the special characters)
user: "scott"
password: "p%40ss%3Aword"

func validateOracleConfig(cfg map[string]any) error {
	methods := 0
	for _, k := range []string{"tnsAlias", "connectionString"} {
		if s, _ := cfg[k].(string); strings.TrimSpace(s) != "" {
			methods++
		}
	}
	if h, _ := cfg["host"].(string); h != "" {
		if sn, _ := cfg["serviceName"].(string); sn != "" {
			methods++
		}
	}
	if methods != 1 {
		return fmt.Errorf("provide exactly one of tnsAlias, connectionString, or host+serviceName")
	}
	if _, ok := cfg["user"]; !ok {
		return fmt.Errorf("user is required")
	}
	if _, ok := cfg["password"]; !ok {
		return fmt.Errorf("password is required")
	}
	return nil
}

func isConnOpenErr(err error) bool {
	return err != nil && strings.Contains(err.Error(), "unable to create Oracle connection")
}

src, err := oracleCfg.Initialize(ctx, tracer)
if err != nil {
	if isConnOpenErr(err) {
		log.Fatalf("oracle source config/DSN invalid: %v", err)
	}
	return err
}

When it happens

Trigger: Initialize is called when the toolbox loads its config and instantiates the 'oracle' source. initOracleConnection fails when sql.Open('godror'|'oracle', connStr) returns an error: malformed connection string built from tnsAlias/connectionString/host+serviceName, invalid URL-escaped user/password, or the OCI driver cannot initialize.

Common situations: Typos or special characters (e.g. '@', ':', '/') in user or password that break the oracle:// URL; an invalid or ambiguous connectString; misconfigured UseOCI so the godror driver is used without Oracle Client libraries installed; config validation passing but the resulting DSN still being invalid.

Related errors

• sql.Open: %w
• unable to connect successfully: %w
• unable to connect successfully: %w
• unable to create pool: %w
• failed to connect to CockroachDB after %d retries: %w

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