{"record":{"id":"ed96ab603f039c60","repo":"t8y2/dbx","slug":"oracle-tns-network-alias-is-invalid","errorCode":null,"errorMessage":"Oracle TNS network alias is invalid","messagePattern":"Oracle TNS network alias is invalid","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/oracle-go/tns.go","lineNumber":54,"sourceCode":"\t}\n\treturn buildGoOraJDBC(params.Username, params.Password, descriptor, options), nil\n}\n\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 {","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/oracle-go/tns.go#L36-L72","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ndsn := \"jdbc:oracle:thin:@?TNS_ADMIN=/opt/oracle/admin\" // empty alias\n// after\ndsn := \"jdbc:oracle:thin:@PROD_DB?TNS_ADMIN=/opt/oracle/admin\"","handlingStrategy":"validation","validationCode":"alias := strings.TrimSpace(strings.SplitN(target, \"?\", 2)[0])\nif alias == \"\" { return errors.New(\"TNS JDBC URL requires a non-empty alias after '@'\") }\nif _, err := url.QueryUnescape(alias); err != nil { return fmt.Errorf(\"invalid percent-encoding in alias: %w\", err) }","typeGuard":null,"tryCatchPattern":"cfg, err := parseOracleTNSJDBCURL(raw)\nif err != nil {\n\tif strings.Contains(err.Error(), \"alias is invalid\") {\n\t\treturn fmt.Errorf(\"check the jdbc:oracle:thin:@<alias>?TNS_ADMIN=... URL: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["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."],"tags":["oracle","tns","config","url-parsing"],"backgroundTag":"invalid-connection-string","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"}