{"record":{"id":"7cecf5d3929e596d","repo":"t8y2/dbx","slug":"oracle-tns-alias-q-was-not-found-in-s","errorCode":null,"errorMessage":"Oracle TNS alias %q was not found in %s","messagePattern":"Oracle TNS alias %q was not found in (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/oracle-go/tns.go","lineNumber":81,"sourceCode":"\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)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdescriptor, ok := aliases[strings.ToUpper(config.Alias)]\n\tif !ok {\n\t\treturn \"\", fmt.Errorf(\"Oracle TNS alias %q was not found in %s\", config.Alias, tnsNamesPath)\n\t}\n\treturn descriptor, nil\n}\n\nfunc oracleTNSNamesPath(tnsAdmin string) (string, error) {\n\tpath := filepath.Clean(strings.TrimSpace(tnsAdmin))\n\tinfo, err := os.Stat(path)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"Oracle TNS_ADMIN directory is not accessible: %s\", path)\n\t}\n\tif !info.IsDir() {\n\t\treturn \"\", fmt.Errorf(\"Oracle TNS_ADMIN must be a directory containing tnsnames.ora: %s\", path)\n\t}\n\ttnsNamesPath := filepath.Join(path, \"tnsnames.ora\")\n\tif info, err := os.Stat(tnsNamesPath); err != nil || info.IsDir() {\n\t\treturn \"\", fmt.Errorf(\"Oracle tnsnames.ora was not found in TNS_ADMIN directory: %s\", path)\n\t}\n\treturn tnsNamesPath, nil","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/oracle-go/tns.go#L63-L99","documentation":"resolveOracleTNSAlias reads tnsnames.ora (following includes) into a map of alias -> descriptor and looks up the requested alias uppercased. If the alias is absent from the file, the driver reports which alias and which tnsnames.ora path it searched.","triggerScenarios":"buildDSNForConnect is called with a TNS alias that does not exist (after uppercasing) in the tnsnames.ora found under the supplied TNS_ADMIN directory.","commonSituations":"Alias defined only in the client's local tnsnames.ora but TNS_ADMIN points elsewhere; case-sensitivity assumptions (alias stored lowercase won't match since lookup uppercases); alias renamed on the server side; stale Docker/container images with old tnsnames.ora.","solutions":["Open the tnsnames.ora at the reported path and confirm the alias is defined (remember lookup is case-insensitive via uppercase).","Point TNS_ADMIN at the directory containing the correct tnsnames.ora for your environment.","Add the missing alias entry, e.g. MYALIAS = (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl))).","Check IFILE includes in tnsnames.ora — the resolver follows them, but a broken include may hide aliases; run the resolver's read with a fixed depth limit in mind."],"exampleFix":"// before\n# tnsnames.ora\nOTHER_ALIAS = (DESCRIPTION=...)\n// after\n# tnsnames.ora\nPROD_DB = (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl)))","handlingStrategy":"fallback","validationCode":"f, err := os.Open(filepath.Join(tnsAdmin, \"tnsnames.ora\"))\nif err != nil { return err }\ndefer f.Close()\ndata, _ := io.ReadAll(f)\nif !strings.Contains(strings.ToUpper(string(data)), strings.ToUpper(alias)) {\n\treturn fmt.Errorf(\"alias %s not present in tnsnames.ora\", alias)\n}","typeGuard":null,"tryCatchPattern":"descriptor, err := resolveOracleTNSAlias(cfg)\nif strings.Contains(err.Error(), \"was not found in\") {\n\t// fall back to a full descriptor embedded in the URL or prompt for the correct alias\n}","preventionTips":["Keep one canonical tnsnames.ora distributed with your deployment and point TNS_ADMIN at it.","Grep the alias in tnsnames.ora during deploy smoke tests.","Remember alias matching is case-insensitive (uppercased); avoid relying on case to differentiate aliases.","Verify IFILE includes resolve in the target environment."],"tags":["oracle","tns","config","alias-resolution"],"backgroundTag":"tns-alias-not-found","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}