{"record":{"id":"02530f677e3657ca","repo":"t8y2/dbx","slug":"oracle-tns-connection-parameters-are-invalid-w","errorCode":null,"errorMessage":"Oracle TNS connection parameters are invalid: %w","messagePattern":"Oracle TNS connection parameters are invalid: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/oracle-go/tns.go","lineNumber":61,"sourceCode":"\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)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tdescriptor, ok := aliases[strings.ToUpper(config.Alias)]","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/oracle-go/tns.go#L43-L79","documentation":"After splitting the TNS JDBC URL target on '?', the driver parses the query component with url.ParseQuery. Malformed query syntax (e.g. a bare '%' or invalid escape like %ZZ) makes parsing fail, and the error is wrapped as \"Oracle TNS connection parameters are invalid: %w\".","triggerScenarios":"buildDSNForConnect is called with a jdbc:oracle URL whose portion after '?' is not a valid URL query — typically bad percent-encoding (\"%\" not followed by two hex digits) or stray characters.","commonSituations":"Manually percent-encoding TNS_ADMIN paths and getting escapes wrong, shell/tooling mangling '%' characters, copying URLs from logs where escapes were re-encoded.","solutions":["Fix the percent-encoding after '?' — e.g. encode spaces as %20 and literal % as %25.","Avoid encoding entirely if the TNS_ADMIN path has no special characters: ?TNS_ADMIN=/opt/oracle/admin.","Use url.QueryUnescape/url.Query building in your own code to generate the URL instead of string concatenation.","Inspect the wrapped %w error to see the exact url.ParseQuery complaint."],"exampleFix":"// before\ndsn := \"jdbc:oracle:thin:@ALIAS?TNS_ADMIN=/opt/my%2app/admin\" // invalid escape %2a mistaken\n// after\ndsn := \"jdbc:oracle:thin:@ALIAS?TNS_ADMIN=\" + url.QueryEscape(\"/opt/my app/admin\")","handlingStrategy":"validation","validationCode":"q := target[strings.Index(target, \"?\")+1:]\nif _, err := url.ParseQuery(q); err != nil {\n\treturn fmt.Errorf(\"malformed query in Oracle JDBC URL: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"var urlErr *url.Error\nif errors.As(err, &urlErr) || strings.Contains(err.Error(), \"connection parameters are invalid\") {\n\treturn fmt.Errorf(\"fix percent-encoding after '?' (use url.QueryEscape): %w\", err)\n}","preventionTips":["Generate the query string with url.Values{\"TNS_ADMIN\": {dir}}.Encode().","Never hand-escape '%'; encode literal % as %25.","Test connection strings through the parser in unit tests before deployment."],"tags":["oracle","tns","url-parsing","config"],"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-14T05:17:10.506Z"}