{"record":{"id":"0712c4a1322c527f","repo":"t8y2/dbx","slug":"oracle-tns-admin-directory-is-required","errorCode":null,"errorMessage":"Oracle TNS_ADMIN directory is required","messagePattern":"Oracle TNS_ADMIN directory is required","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/oracle-go/tns.go","lineNumber":57,"sourceCode":"\nfunc parseOracleTNSJDBCURL(value string) (oracleTNSConfig, bool, error) {\n\tsource := strings.TrimSpace(value)\n\tif !strings.HasPrefix(strings.ToLower(source), oracleJDBCThinPrefix) {\n\t\treturn oracleTNSConfig{}, false, nil\n\t}\n\n\ttarget := strings.TrimSpace(source[len(oracleJDBCThinPrefix):])\n\tif target == \"\" || strings.HasPrefix(target, \"(\") || strings.HasPrefix(target, \"//\") || strings.Contains(strings.SplitN(target, \"?\", 2)[0], \":\") {\n\t\treturn oracleTNSConfig{}, false, nil\n\t}\n\n\tparts := strings.SplitN(target, \"?\", 2)\n\talias, err := url.QueryUnescape(strings.TrimSpace(parts[0]))\n\tif err != nil || strings.TrimSpace(alias) == \"\" {\n\t\treturn oracleTNSConfig{}, true, fmt.Errorf(\"Oracle TNS network alias is invalid\")\n\t}\n\tif len(parts) == 1 {\n\t\treturn oracleTNSConfig{}, true, fmt.Errorf(\"Oracle TNS_ADMIN directory is required\")\n\t}\n\tquery, err := url.ParseQuery(parts[1])\n\tif err != nil {\n\t\treturn oracleTNSConfig{}, true, fmt.Errorf(\"Oracle TNS connection parameters are invalid: %w\", err)\n\t}\n\ttnsAdmin := strings.TrimSpace(query.Get(\"TNS_ADMIN\"))\n\tif tnsAdmin == \"\" {\n\t\treturn oracleTNSConfig{}, true, fmt.Errorf(\"Oracle TNS_ADMIN directory is required\")\n\t}\n\treturn oracleTNSConfig{Alias: strings.TrimSpace(alias), TNSAdmin: tnsAdmin}, true, nil\n}\n\nfunc resolveOracleTNSAlias(config oracleTNSConfig) (string, error) {\n\ttnsNamesPath, err := oracleTNSNamesPath(config.TNSAdmin)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\taliases, err := readOracleTNSAliases(tnsNamesPath, make(map[string]bool), 0)","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/oracle-go/tns.go#L39-L75","documentation":"parseOracleTNSJDBCURL requires a query string in the JDBC-style URL. If the target contains no '?' (len(parts) == 1), there is nowhere to carry TNS_ADMIN, so the driver rejects the URL demanding a TNS_ADMIN directory specification.","triggerScenarios":"buildDSNForConnect is given jdbc:oracle:thin:@ALIAS with no '?TNS_ADMIN=...' query component, so the parser cannot locate the tnsnames.ora directory.","commonSituations":"Migrating from a plain host:port DSN to TNS alias form and forgetting the TNS_ADMIN query parameter; environment variables set but URL not updated; trimming the URL at '?' by mistake.","solutions":["Append the query component: jdbc:oracle:thin:@ALIAS?TNS_ADMIN=/path/to/tnsadmin.","Alternatively set the TNS_ADMIN environment variable and verify the driver picks it up, per the library's documented config precedence.","If you meant a plain host DSN, use the non-TNS URL form instead of an alias.","Check that the URL wasn't truncated when copied from documentation or a secret manager."],"exampleFix":"// before\ndsn := \"jdbc:oracle:thin:@PROD_DB\" // no TNS_ADMIN\n// after\ndsn := \"jdbc:oracle:thin:@PROD_DB?TNS_ADMIN=/opt/oracle/network/admin\"","handlingStrategy":"validation","validationCode":"if !strings.Contains(target, \"?\") || !strings.Contains(target, \"TNS_ADMIN=\") {\n\treturn errors.New(\"TNS JDBC URL must include ?TNS_ADMIN=<dir>\")\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"TNS_ADMIN directory is required\") {\n\treturn fmt.Errorf(\"append ?TNS_ADMIN=/path/to/admin to the Oracle JDBC URL: %w\", err)\n}","preventionTips":["Standardize a DSN template that always includes ?TNS_ADMIN=... for alias-based URLs.","Fail fast in config loading if an alias-form URL lacks TNS_ADMIN.","Document the difference between host:port DSNs and TNS alias URLs for your team."],"tags":["oracle","tns","config","missing-parameter"],"backgroundTag":"missing-env-var","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}