t8y2/dbx · error

Oracle TNS alias %q was not found in %s

Error message

Oracle TNS alias %q was not found in %s

What it means

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.

Source

Thrown at agents/drivers/oracle-go/tns.go:81

	tnsAdmin := strings.TrimSpace(query.Get("TNS_ADMIN"))
	if tnsAdmin == "" {
		return oracleTNSConfig{}, true, fmt.Errorf("Oracle TNS_ADMIN directory is required")
	}
	return oracleTNSConfig{Alias: strings.TrimSpace(alias), TNSAdmin: tnsAdmin}, true, nil
}

func resolveOracleTNSAlias(config oracleTNSConfig) (string, error) {
	tnsNamesPath, err := oracleTNSNamesPath(config.TNSAdmin)
	if err != nil {
		return "", err
	}
	aliases, err := readOracleTNSAliases(tnsNamesPath, make(map[string]bool), 0)
	if err != nil {
		return "", err
	}
	descriptor, ok := aliases[strings.ToUpper(config.Alias)]
	if !ok {
		return "", fmt.Errorf("Oracle TNS alias %q was not found in %s", config.Alias, tnsNamesPath)
	}
	return descriptor, nil
}

func oracleTNSNamesPath(tnsAdmin string) (string, error) {
	path := filepath.Clean(strings.TrimSpace(tnsAdmin))
	info, err := os.Stat(path)
	if err != nil {
		return "", fmt.Errorf("Oracle TNS_ADMIN directory is not accessible: %s", path)
	}
	if !info.IsDir() {
		return "", fmt.Errorf("Oracle TNS_ADMIN must be a directory containing tnsnames.ora: %s", path)
	}
	tnsNamesPath := filepath.Join(path, "tnsnames.ora")
	if info, err := os.Stat(tnsNamesPath); err != nil || info.IsDir() {
		return "", fmt.Errorf("Oracle tnsnames.ora was not found in TNS_ADMIN directory: %s", path)
	}
	return tnsNamesPath, nil

View on GitHub (pinned to c0390bff16)

Solutions

  1. Open the tnsnames.ora at the reported path and confirm the alias is defined (remember lookup is case-insensitive via uppercase).
  2. Point TNS_ADMIN at the directory containing the correct tnsnames.ora for your environment.
  3. Add the missing alias entry, e.g. MYALIAS = (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl))).
  4. 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.

Example fix

// before
# tnsnames.ora
OTHER_ALIAS = (DESCRIPTION=...)
// after
# tnsnames.ora
PROD_DB = (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl)))
Defensive patterns

Strategy: fallback

Validate before calling

f, err := os.Open(filepath.Join(tnsAdmin, "tnsnames.ora"))
if err != nil { return err }
defer f.Close()
data, _ := io.ReadAll(f)
if !strings.Contains(strings.ToUpper(string(data)), strings.ToUpper(alias)) {
	return fmt.Errorf("alias %s not present in tnsnames.ora", alias)
}

Try / catch

descriptor, err := resolveOracleTNSAlias(cfg)
if strings.Contains(err.Error(), "was not found in") {
	// fall back to a full descriptor embedded in the URL or prompt for the correct alias
}

Prevention

When it happens

Trigger: buildDSNForConnect is called with a TNS alias that does not exist (after uppercasing) in the tnsnames.ora found under the supplied TNS_ADMIN directory.

Common situations: 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.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/7cecf5d3929e596d. Report an issue: GitHub.