OpenAPITools/openapi-generator · error · IllegalArgumentException

%s file suffix only allows '.', '-' and alphanumeric charact

Error message

%s file suffix only allows '.', '-' and alphanumeric characters.

What it means

The typescript-nestjs server generator validates the file-suffix options 'apiFileSuffix' and 'modelFileSuffix' against ^[a-zA-Z0-9.-]*$ (TypeScriptNestjsServerCodegen.java:49, validated at lines 227/235). Unlike the client variant, this check is guarded by 'value != null', so an unset suffix passes; only a non-null value containing characters outside '.', '-' and alphanumerics throws. %s in the message is 'Service' or 'Model'.

Source

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

            result = result.substring(prefix.length());
        }
        if (suffix.length() > 0 && result.endsWith(suffix)) {
            result = result.substring(0, result.length() - suffix.length());
        }

        return result;
    }

    /**
     * Validates that the given string value only contains '-', '.' and 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 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)
            );
        }

View on GitHub (pinned to fcec517be3)

Solutions

  1. Restrict the suffix to letters, digits, '.' and '-' (e.g. '.api' instead of '_api').
  2. Check apiFileSuffix and modelFileSuffix — the %s label ('Service'/'Model') tells you which failed.
  3. Alternatively omit the suffix option entirely; null values are accepted by the server generator.

Example fix

# before
openapi-generator-cli generate -g typescript-nestjs-server \
  -DapiFileSuffix=_api

# after
openapi-generator-cli generate -g typescript-nestjs-server \
  -DapiFileSuffix=.api
Defensive patterns

Strategy: validation

Validate before calling

if ! printf '%s' "$API_FILE_SUFFIX$MODEL_FILE_SUFFIX" | grep -Eq '^[a-zA-Z0-9.-]*$'; then
  echo "ERROR: file suffixes may only contain '.', '-' and alphanumerics" >&2
  exit 1
fi

Type guard

const isValidFileSuffix = (v: string | null | undefined): boolean =>
  v == null || /^[a-zA-Z0-9.-]*$/.test(v); // null is accepted by the server generator

Try / catch

catch (IllegalArgumentException e) {
    throw new RuntimeException("Invalid typescript-nestjs-server suffix option: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Generating a NestJS server with -DapiFileSuffix=_api or -DmodelFileSuffix=.gen.model.ts? — any non-null suffix matching [^a-zA-Z0-9.-] (underscore, space, slash) throws during processOpts. Note the option is named apiFileSuffix but the message label is 'Service'.

Common situations: Server scaffolds that follow snake_case file conventions; sharing one -D options string between client and server generation where the client uses serviceFileSuffix and the server apiFileSuffix; trailing whitespace in CI variables.

Related errors

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