What causes "Invalid query param object format '%s'. Must be one of %s." in OpenAPITools/openapi-generator?

Use one of the supported values: 'key', 'json' or 'dot'.

OpenAPITools/openapi-generator · error · IllegalArgumentException

Invalid query param object format '%s'. Must be one of %s.

Error message

Invalid query param object format '%s'. Must be one of %s.

What it means

queryParamObjectFormat controls how objects are serialized into query parameters. The value is parsed into an enum whose only members are 'dot', 'json' and 'key'; any other string triggers IllegalArgumentException, with the accepted list included in the message.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/TypeScriptAngularClientCodegen.java:714

            );
        }
    }

    /**
     * Set the query param object format.
     *
     * @param format the query param object format to use
     */
    public void setQueryParamObjectFormat(String format) {
        try {
            queryParamObjectFormat = QUERY_PARAM_OBJECT_FORMAT_TYPE.valueOf(format);
        } catch (IllegalArgumentException e) {
            String values = Stream.of(QUERY_PARAM_OBJECT_FORMAT_TYPE.values())
                    .map(value -> "'" + value.name() + "'")
                    .collect(Collectors.joining(", "));

            String msg = String.format(Locale.ROOT, "Invalid query param object format '%s'. Must be one of %s.", format, values);
            throw new IllegalArgumentException(msg);
        }
    }

    /**
     * Set the file naming type.
     *
     * @param fileNaming the file naming to use
     */
    private void setFileNaming(String fileNaming) {
        if ("camelCase".equals(fileNaming) || "kebab-case".equals(fileNaming)) {
            this.fileNaming = fileNaming;
        } else {
            throw new IllegalArgumentException("Invalid file naming '" +
                    fileNaming + "'. Must be 'camelCase' or 'kebab-case'");
        }
    }

    /**

View on GitHub (pinned to fcec517be3)

Solutions

Use one of the supported values: 'key', 'json' or 'dot'.
Omit the option to keep the default serialization.

Example fix

# before
-DqueryParamObjectFormat=nestjs

# after
-DqueryParamObjectFormat=key

Defensive patterns

Strategy: type-guard

Validate before calling

// node: verify the value before passing it to the generator
const FORMATS = ['dot', 'json', 'key'];
if (opts.queryParamObjectFormat && !FORMATS.includes(opts.queryParamObjectFormat))
  throw new Error(`queryParamObjectFormat must be one of ${FORMATS.join('|')}`);

Type guard

const QUERY_PARAM_FORMATS = ['dot', 'json', 'key'] as const;
export type QueryParamFormat = typeof QUERY_PARAM_FORMATS[number];
const isQueryParamFormat = (v: string): v is QueryParamFormat =>
  (QUERY_PARAM_FORMATS as readonly string[]).includes(v);

Try / catch

// Java
try { new DefaultGenerator().opts(input).generate(); }
catch (IllegalArgumentException e) {
    // message lists the accepted values; correct the option and rerun once
}

Prevention

Model generator enums in your config code as union types, not raw strings.
Check the enum values in the generator's message rather than guessing serialization names.
Centralize option constants in one module consumed by all generation scripts.

When it happens

Trigger: -DqueryParamObjectFormat=nestjs, 'key-value', 'brackets' or any value other than dot/json/key.

Common situations: Guessing serialization names from other ecosystems (nestjs, qs-style 'brackets', 'comma'); copying the option from a different generator with another value set; typos like 'Json'.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/cb189c229f7edb80. Report an issue: GitHub.