{"record":{"id":"6bd4481c61226888","repo":"googleapis/mcp-toolbox","slug":"unable-to-create-oracle-connection-w","errorCode":null,"errorMessage":"unable to create Oracle connection: %w","messagePattern":"unable to create Oracle connection: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/sources/oracle/oracle.go","lineNumber":106,"sourceCode":"\tif hasTnsAdmin && !c.UseOCI {\n\t\treturn fmt.Errorf(\"`tnsAdmin` can only be used when `UseOCI` is true, or use `walletLocation` instead\")\n\t}\n\n\tif hasWallet && c.UseOCI {\n\t\treturn fmt.Errorf(\"when using an OCI driver, use `tnsAdmin` to specify credentials file location instead\")\n\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 {","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/oracle/oracle.go#L88-L124","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped cause (%w) in the error message for the driver-specific failure reason.","Verify the connection method in your YAML: exactly one of tnsAlias, connectionString, or host+serviceName, with correct host/port/serviceName values.","URL-encode special characters in user/password, or percent-encode them in config (the source decodes percent-encoded values).","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.","Enable debug logging to see the exact serverString/driver used and compare with a working sqlplus/SQLcl connection."],"exampleFix":"// before (special chars break the oracle:// URL)\nuser: \"scott\"\npassword: \"p@ss:word\"\n// after (percent-encode the special characters)\nuser: \"scott\"\npassword: \"p%40ss%3Aword\"","handlingStrategy":"validation","validationCode":"func validateOracleConfig(cfg map[string]any) error {\n\tmethods := 0\n\tfor _, k := range []string{\"tnsAlias\", \"connectionString\"} {\n\t\tif s, _ := cfg[k].(string); strings.TrimSpace(s) != \"\" {\n\t\t\tmethods++\n\t\t}\n\t}\n\tif h, _ := cfg[\"host\"].(string); h != \"\" {\n\t\tif sn, _ := cfg[\"serviceName\"].(string); sn != \"\" {\n\t\t\tmethods++\n\t\t}\n\t}\n\tif methods != 1 {\n\t\treturn fmt.Errorf(\"provide exactly one of tnsAlias, connectionString, or host+serviceName\")\n\t}\n\tif _, ok := cfg[\"user\"]; !ok {\n\t\treturn fmt.Errorf(\"user is required\")\n\t}\n\tif _, ok := cfg[\"password\"]; !ok {\n\t\treturn fmt.Errorf(\"password is required\")\n\t}\n\treturn nil\n}","typeGuard":"func isConnOpenErr(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"unable to create Oracle connection\")\n}","tryCatchPattern":"src, err := oracleCfg.Initialize(ctx, tracer)\nif err != nil {\n\tif isConnOpenErr(err) {\n\t\tlog.Fatalf(\"oracle source config/DSN invalid: %v\", err)\n\t}\n\treturn err\n}","preventionTips":["Keep exactly one connection method in config: tnsAlias, connectionString, or host+serviceName.","Percent-encode special characters (@, :, /) in user and password.","If useOCI is true, verify Oracle Client libraries are installed before starting the toolbox.","Validate the config at deploy time with a startup smoke test that initializes the source."],"tags":["oracle","database","connection","config"],"backgroundTag":"database-connection-open-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"}