googleapis/mcp-toolbox · critical

unable to connect to Oracle successfully: %w

Error message

unable to connect to Oracle successfully: %w

What it means

Thrown by Config.Initialize after the sql.DB handle was created but db.PingContext failed, meaning the driver could not establish a live session with the Oracle server. The source closes the pool and returns this error wrapping the driver's ping error. It indicates the database was reachable-configured but the actual network/auth handshake failed (or the context was cancelled).

Source

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

	}

	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 {
	Config
	DB *sql.DB
}

func (s *Source) IsReadOnly() bool {
	return false

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Read the wrapped ORA-xxxxx / driver error to classify: network (ORA-12170/12541), auth (ORA-01017), or service (ORA-12514).
  2. Test the same host/port/service with `sqlplus user/pass@host:1521/service` from the toolbox host to isolate network vs config.
  3. Verify credentials and that the user account is not locked/expired.
  4. If using tnsAlias/tnsAdmin (useOCI), confirm TNS_ADMIN contains tnsnames.ora (and wallet files) with the alias defined.
  5. If using walletLocation (go-ora), confirm the wallet directory exists and is readable, and ssl=true is appropriate.
  6. Check startup timeout/context: if the DB is slow to accept sessions, ensure the context is not cancelled prematurely.

Example fix

// before (unreachable service name)
host: "db.example.com"
port: 1521
serviceName: "orclPDB1.typo"
// after (correct service name verified via lsnrctl status)
host: "db.example.com"
port: 1521
serviceName: "orclPDB1"
Defensive patterns

Strategy: retry

Validate before calling

// probe reachability before initializing the source
conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), 5*time.Second)
if err != nil {
	return fmt.Errorf("oracle host %s:%d unreachable: %w", host, port, err)
}
conn.Close()

Type guard

func isPingFailure(err error) bool {
	return err != nil && strings.Contains(err.Error(), "unable to connect to Oracle successfully")
}

Try / catch

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
	if isPingFailure(err) {
		if strings.Contains(err.Error(), "ORA-01017") {
			return fmt.Errorf("check oracle credentials: %w", err)
		}
		if strings.Contains(err.Error(), "ORA-") {
			return retryWithBackoff(ctx, 3, func() error { return reinitialize(ctx, tracer) })
		}
	}
	return err
}

Prevention

When it happens

Trigger: Any toolbox startup (source Initialize) where sql.Open succeeds but PingContext errors: server host/port unreachable, listener not running, wrong service name, ORA-01017 invalid username/password, expired wallet credentials, or ctx deadline exceeded during startup.

Common situations: Firewall or VPN blocking port 1521; typo in serviceName or tnsAlias not present in tnsnames.ora; rotated DB credentials not yet updated in toolbox config; TNS_ADMIN pointing at a directory without the right wallet/tnsnames files; Oracle database down for maintenance.

Related errors

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