Oracle TNS connection parameters are invalid: %w

Error message

Oracle TNS connection parameters are invalid: %w

What it means

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".

Source

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

		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 {
		return "", err
	}
	aliases, err := readOracleTNSAliases(tnsNamesPath, make(map[string]bool), 0)
	if err != nil {
		return "", err
	}
	descriptor, ok := aliases[strings.ToUpper(config.Alias)]

View on GitHub (pinned to c0390bff16)

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.

Example fix

// before
dsn := "jdbc:oracle:thin:@ALIAS?TNS_ADMIN=/opt/my%2app/admin" // invalid escape %2a mistaken
// after
dsn := "jdbc:oracle:thin:@ALIAS?TNS_ADMIN=" + url.QueryEscape("/opt/my app/admin")

Defensive patterns

Strategy: validation

Validate before calling

q := target[strings.Index(target, "?")+1:]
if _, err := url.ParseQuery(q); err != nil {
	return fmt.Errorf("malformed query in Oracle JDBC URL: %w", err)
}

Try / catch

var urlErr *url.Error
if errors.As(err, &urlErr) || strings.Contains(err.Error(), "connection parameters are invalid") {
	return fmt.Errorf("fix percent-encoding after '?' (use url.QueryEscape): %w", err)
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Manually percent-encoding TNS_ADMIN paths and getting escapes wrong, shell/tooling mangling '%' characters, copying URLs from logs where escapes were re-encoded.

Related errors

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