What causes "%s class suffix only allows alphanumeric characters." in OpenAPITools/openapi-generator?

Use a purely alphanumeric suffix such as -DserviceSuffix=Service or -DmodelSuffix=DTO.

OpenAPITools/openapi-generator · error · IllegalArgumentException

%s class suffix only allows alphanumeric characters.

Error message

%s class suffix only allows alphanumeric characters.

What it means

Class-suffix options (serviceSuffix, modelSuffix) are validated for alphanumeric-only content, since the suffix becomes part of generated class names (e.g. PetService, PetModel). Any non-alphanumeric character in the suffix aborts generation during option processing.

Source

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

     */
    private void validateClassPrefixArgument(String argument, String value) {
        if (!value.matches(CLASS_NAME_PREFIX_PATTERN)) {
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT, "%s class prefix only allows alphanumeric characters.", argument)
            );
        }
    }

    /**
     * Validates that the given string value only contains alpha numeric characters.
     * Throws an IllegalArgumentException, if the string contains any other characters.
     *
     * @param argument The name of the argument being validated. This is only used for displaying an error message.
     * @param value    The value that is being validated.
     */
    private void validateClassSuffixArgument(String argument, String value) {
        if (!value.matches(CLASS_NAME_SUFFIX_PATTERN)) {
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT, "%s class suffix only allows alphanumeric characters.", argument)
            );
        }
    }

    /**
     * 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(", "));

View on GitHub (pinned to fcec517be3)

Solutions

Use a purely alphanumeric suffix such as -DserviceSuffix=Service or -DmodelSuffix=DTO.
Omit the suffix option to keep generator defaults.
Put version markers in the prefix or package names, not the class suffix.

Example fix

# before
-DserviceSuffix=_Service

# after
-DserviceSuffix=Service

Defensive patterns

Strategy: validation

Validate before calling

// node: class suffixes must be alphanumeric
const ALNUM = /^[A-Za-z0-9]+$/;
for (const [k, v] of Object.entries({ serviceSuffix: opts.serviceSuffix, modelSuffix: opts.modelSuffix }))
  if (v && !ALNUM.test(v)) throw new Error(`${k} must be alphanumeric, got: ${v}`);

Type guard

const isValidClassSuffix = (v: string): boolean => /^[A-Za-z0-9]+$/.test(v);

Try / catch

// Java
try { new DefaultGenerator().opts(input).generate(); }
catch (IllegalArgumentException e) {
    // suffix rejected: use a plain word like 'Service' or 'DTO'
}

Prevention

Keep version markers out of class suffixes; use prefixes or package names.
Lint naming options in CI before generation.
Reuse the same suffix conventions across teams to avoid one-off invalid values.

When it happens

Trigger: -DserviceSuffix=_Service or -DmodelSuffix=Dto/v2 — any suffix containing characters other than [A-Za-z0-9].

Common situations: Teams adding version markers like 'V2' with slashes or dots; snake_case suffix habits; suffixes copied from file-name conventions rather than class-name conventions.

Related errors

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