OpenAPITools/openapi-generator · error · IllegalArgumentException

%s class suffix only allows alphanumeric characters.

Error message

%s class suffix only allows alphanumeric characters.

What it means

The typescript-nestjs server generator validates the class-suffix options 'apiSuffix' and 'modelSuffix' against ^[a-zA-Z0-9]*$ (TypeScriptNestjsServerCodegen.java:48, validated at lines 223/231). The value is appended to generated TypeScript class names, so dots, dashes and underscores are rejected; a null value is allowed (value != null guard) and simply skips validation. %s is 'Service' or 'Model'.

Source

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

     */
    private void validateFileSuffixArgument(String argument, String value) {
        if (value != null && !value.matches(FILE_NAME_SUFFIX_PATTERN)) {
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT, "%s file suffix only allows '.', '-' and 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 != null && !value.matches(CLASS_NAME_SUFFIX_PATTERN)) {
            throw new IllegalArgumentException(
                    String.format(Locale.ROOT, "%s class suffix only allows alphanumeric characters.", argument)
            );
        }
    }

    /**
     * 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

  1. Use a purely alphanumeric class suffix ('Controller', 'Service', 'Api').
  2. Keep dotted/dashed naming for apiFileSuffix/modelFileSuffix only.
  3. Omit the option if the default suffix is acceptable — null passes validation.

Example fix

# before
openapi-generator-cli generate -g typescript-nestjs-server \
  -DapiSuffix=.Controller

# after
openapi-generator-cli generate -g typescript-nestjs-server \
  -DapiSuffix=Controller
Defensive patterns

Strategy: validation

Validate before calling

if ! printf '%s' "$API_SUFFIX$MODEL_SUFFIX" | grep -Eq '^[a-zA-Z0-9]*$'; then
  echo "ERROR: class suffixes must be purely alphanumeric" >&2
  exit 1
fi

Type guard

const isValidClassSuffix = (v: string | null | undefined): boolean =>
  v == null || /^[a-zA-Z0-9]*$/.test(v);

Prevention

When it happens

Trigger: Passing -DapiSuffix=.Controller or -DmodelSuffix=My-Model — any non-null suffix with a non-alphanumeric character throws during processOpts. The option key is apiSuffix but the error label reads 'Service'.

Common situations: Wanting generated controller classes named like 'UserController' by passing '.Controller'; copying the same suffix into both apiSuffix and apiFileSuffix; migrating from the client generator where option names differ.

Related errors

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