quarkusio/quarkus · error · IllegalArgumentException

failed to encode options params

Error message

failed to encode options params

What it means

PostgreSQLServiceBindingConverter.formatUrl() URL-encodes the combined connection 'options' parameter (e.g. search_path and SSL parameters) taken from a service binding secret. If the platform charset is unsupported, URLEncoder.encode throws UnsupportedEncodingException, which is wrapped into this IllegalArgumentException. It signals the service-binding-generated options string could not be turned into a safe JDBC URL.

Source

Thrown at extensions/jdbc/jdbc-postgresql/runtime/src/main/java/io/quarkus/jdbc/postgresql/runtime/PostgreSQLServiceBindingConverter.java:90

                    }
                }
            }

            String combinedOptions = crdbOption;
            if (postgreOptions.size() > 0) {
                String otherOpts = String.join(" ", postgreOptions);
                if (!combinedOptions.equals("")) {
                    combinedOptions = combinedOptions + " " + otherOpts;
                } else {
                    combinedOptions = otherOpts;
                }
            }

            try {
                combinedOptions = combinedOptions.length() > 0 ? OPTIONS + "=" + encode(combinedOptions).replace("+", "%20")
                        : "";
            } catch (UnsupportedEncodingException e) {
                throw new IllegalArgumentException("failed to encode options params" + options, e);
            }

            if (sslparam.length() > 0 && !combinedOptions.equals("")) {
                combinedOptions = sslparam + "&" + combinedOptions;
            } else if (sslparam.length() > 0) {
                combinedOptions = sslparam.toString();
            }

            if (!"".equals(combinedOptions)) {
                //append sslmode and options to the URL
                result += "?" + combinedOptions;
            }

            return result;
        }

        private String encode(String str) throws UnsupportedEncodingException {
            return URLEncoder.encode(str, StandardCharsets.UTF_8.toString());

View on GitHub (pinned to e1c734241f)

Solutions

  1. Ensure the runtime image/JVM supports the UTF-8 charset (use a full JDK or a base image with charsets included).
  2. Check the service binding secret's 'options' value for invalid or non-standard content and fix the binding.
  3. Upgrade the Quarkus postgresql extension: newer code uses StandardCharsets/encode(float) style APIs that cannot throw this.
  4. As a workaround, build the JDBC URL manually from the binding values instead of relying on the converter.

Example fix

// before: rely on service binding converter with restricted runtime
quarkus.datasource.jdbc.url=<from binding secret options>
// after: set URL explicitly and pre-encode options
quarkus.datasource.jdbc.url=jdbc:postgresql://host/db?options=-c%20search_path%3Dmyschema
Defensive patterns

Strategy: try-catch

Validate before calling

boolean charsetOk;
try {
    "x".getBytes("UTF-8");
    charsetOk = true;
} catch (UnsupportedEncodingException e) {
    charsetOk = false;
}

Try / catch

try {
    URL url = converter.formatUrl(binding);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("failed to encode options params")) {
        log.error("Service binding options not encodable; check secret content and runtime charset", e);
    } else { throw e; }
}

Prevention

When it happens

Trigger: Binding a PostgreSQL datasource via a Kubernetes service binding whose secret contains an 'options' field, while URLEncoder.encode(String, "UTF-8") throws UnsupportedEncodingException (charset unavailable in the runtime environment).

Common situations: Running on a JRE image missing the charset; exotic native-image builds stripping charsets; malformed binding secrets producing unexpected options values.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/823884a548ce7db1. Report an issue: GitHub.