{"record":{"id":"0e7188a9228e355f","repo":"googleapis/mcp-toolbox","slug":"unable-to-connect-to-oracle-successfully-w","errorCode":null,"errorMessage":"unable to connect to Oracle successfully: %w","messagePattern":"unable to connect to Oracle successfully: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/sources/oracle/oracle.go","lineNumber":112,"sourceCode":"\t}\n\n\treturn nil\n}\n\nfunc (r Config) SourceConfigType() string {\n\treturn SourceType\n}\n\nfunc (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {\n\tdb, err := initOracleConnection(ctx, tracer, r)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to create Oracle connection: %w\", err)\n\t}\n\n\terr = db.PingContext(ctx)\n\tif err != nil {\n\t\tdb.Close()\n\t\treturn nil, fmt.Errorf(\"unable to connect to Oracle successfully: %w\", err)\n\t}\n\n\ts := &Source{\n\t\tConfig: r,\n\t\tDB:     db,\n\t}\n\treturn s, nil\n}\n\nvar _ sources.Source = &Source{}\n\ntype Source struct {\n\tConfig\n\tDB *sql.DB\n}\n\nfunc (s *Source) IsReadOnly() bool {\n\treturn false","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/oracle/oracle.go#L94-L130","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped ORA-xxxxx / driver error to classify: network (ORA-12170/12541), auth (ORA-01017), or service (ORA-12514).","Test the same host/port/service with `sqlplus user/pass@host:1521/service` from the toolbox host to isolate network vs config.","Verify credentials and that the user account is not locked/expired.","If using tnsAlias/tnsAdmin (useOCI), confirm TNS_ADMIN contains tnsnames.ora (and wallet files) with the alias defined.","If using walletLocation (go-ora), confirm the wallet directory exists and is readable, and ssl=true is appropriate.","Check startup timeout/context: if the DB is slow to accept sessions, ensure the context is not cancelled prematurely."],"exampleFix":"// before (unreachable service name)\nhost: \"db.example.com\"\nport: 1521\nserviceName: \"orclPDB1.typo\"\n// after (correct service name verified via lsnrctl status)\nhost: \"db.example.com\"\nport: 1521\nserviceName: \"orclPDB1\"","handlingStrategy":"retry","validationCode":"// probe reachability before initializing the source\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)), 5*time.Second)\nif err != nil {\n\treturn fmt.Errorf(\"oracle host %s:%d unreachable: %w\", host, port, err)\n}\nconn.Close()","typeGuard":"func isPingFailure(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"unable to connect to Oracle successfully\")\n}","tryCatchPattern":"src, err := cfg.Initialize(ctx, tracer)\nif err != nil {\n\tif isPingFailure(err) {\n\t\tif strings.Contains(err.Error(), \"ORA-01017\") {\n\t\t\treturn fmt.Errorf(\"check oracle credentials: %w\", err)\n\t\t}\n\t\tif strings.Contains(err.Error(), \"ORA-\") {\n\t\t\treturn retryWithBackoff(ctx, 3, func() error { return reinitialize(ctx, tracer) })\n\t\t}\n\t}\n\treturn err\n}","preventionTips":["Smoke-test connectivity with sqlplus or SQLcl from the same host/network before deploying.","Keep credentials in a secret manager and rotate them in sync with the database.","Ensure TNS_ADMIN/wallet directories are mounted and readable in containerized deployments.","Monitor listener status and database availability to catch outages before toolbox startup."],"tags":["oracle","database","network","authentication","ping"],"backgroundTag":"database-connection-refused","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"}