t8y2/dbx · error
Oracle TNS network alias is invalid
Error message
Oracle TNS network alias is invalid
What it means
parseOracleTNSJDBCURL converts an Oracle JDBC-style URL (jdbc:oracle:thin:@alias?TNS_ADMIN=...) into a TNS config. After splitting the target on '?', it URL-unescapes the alias portion; if unescaping fails or the alias is empty/whitespace, it reports the alias as invalid.
Source
Thrown at agents/drivers/oracle-go/tns.go:54
}
return buildGoOraJDBC(params.Username, params.Password, descriptor, options), nil
}
func parseOracleTNSJDBCURL(value string) (oracleTNSConfig, bool, error) {
source := strings.TrimSpace(value)
if !strings.HasPrefix(strings.ToLower(source), oracleJDBCThinPrefix) {
return oracleTNSConfig{}, false, nil
}
target := strings.TrimSpace(source[len(oracleJDBCThinPrefix):])
if target == "" || strings.HasPrefix(target, "(") || strings.HasPrefix(target, "//") || strings.Contains(strings.SplitN(target, "?", 2)[0], ":") {
return oracleTNSConfig{}, false, nil
}
parts := strings.SplitN(target, "?", 2)
alias, err := url.QueryUnescape(strings.TrimSpace(parts[0]))
if err != nil || strings.TrimSpace(alias) == "" {
return oracleTNSConfig{}, true, fmt.Errorf("Oracle TNS network alias is invalid")
}
if len(parts) == 1 {
return oracleTNSConfig{}, true, fmt.Errorf("Oracle TNS_ADMIN directory is required")
}
query, err := url.ParseQuery(parts[1])
if err != nil {
return oracleTNSConfig{}, true, fmt.Errorf("Oracle TNS connection parameters are invalid: %w", err)
}
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 {View on GitHub (pinned to c0390bff16)
Solutions
- Supply a non-empty alias after '@' in the JDBC URL, e.g. jdbc:oracle:thin:@MYALIAS?TNS_ADMIN=/path/to/admin.
- Remove stray whitespace around the alias.
- Fix invalid percent-encoding in the alias (only valid URL escapes like %20 are accepted).
- Validate the connection string before passing it to buildDSNForConnect.
Example fix
// before dsn := "jdbc:oracle:thin:@?TNS_ADMIN=/opt/oracle/admin" // empty alias // after dsn := "jdbc:oracle:thin:@PROD_DB?TNS_ADMIN=/opt/oracle/admin"
Defensive patterns
Strategy: validation
Validate before calling
alias := strings.TrimSpace(strings.SplitN(target, "?", 2)[0])
if alias == "" { return errors.New("TNS JDBC URL requires a non-empty alias after '@'") }
if _, err := url.QueryUnescape(alias); err != nil { return fmt.Errorf("invalid percent-encoding in alias: %w", err) } Try / catch
cfg, err := parseOracleTNSJDBCURL(raw)
if err != nil {
if strings.Contains(err.Error(), "alias is invalid") {
return fmt.Errorf("check the jdbc:oracle:thin:@<alias>?TNS_ADMIN=... URL: %w", err)
}
return err
} Prevention
- Keep aliases as plain uppercase tokens with no spaces or percent characters.
- Build connection strings with url.URL/url.Values instead of string concatenation.
- Lint JDBC URLs in CI with a regexp requiring a non-empty alias.
- Validate config at startup, not at first connection attempt.
When it happens
Trigger: Calling buildDSNForConnect with a jdbc:oracle URL whose target before '?' is empty, only whitespace, or percent-encoded characters that do not form a valid query-unescaped string (e.g. @%ZZ).
Common situations: Hand-edited connection strings, copying a JDBC URL and deleting the alias, double-encoding the alias, or leaving '@' with nothing after it in the DSN/environment config.
Related errors
- Oracle TNS connection parameters are invalid: %w
- Oracle TNS_ADMIN directory is required
- Oracle TNS alias %q was not found in %s
- Oracle TNS_ADMIN directory is not accessible: %s
- Oracle TNS_ADMIN must be a directory containing tnsnames.ora
AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05).
Data as JSON: /api/errors/ed96ab603f039c60.
Report an issue: GitHub.