What causes "%s file suffix only allows '.', '-' and alphanumeric characters." in OpenAPITools/openapi-generator?

Change the suffix to use only letters, digits, '.' and '-' (e.g. replace '_service' with '.service' or '-service').

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 client generator validates the file-name suffix options 'serviceFileSuffix' and 'modelFileSuffix' against the regex ^[a-zA-Z0-9.-]*$ (TypeScriptNestjsClientCodegen.java:48, validated at lines 191/199). When a suffix contains any other character (underscore, space, slash, '$'), generation aborts with this IllegalArgumentException, where %s is 'Service' or 'Model'. It is a fail-fast guard: the suffix is concatenated into emitted file names, so an illegal character would produce invalid or unsafe paths.

Source

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

            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.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.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

Change the suffix to use only letters, digits, '.' and '-' (e.g. replace '_service' with '.service' or '-service').
Check both option keys in your command/config: serviceFileSuffix and modelFileSuffix — the %s in the message tells you which one ('Service' or 'Model') is invalid.
If you truly need underscores in generated file names, post-process the output with a rename script after generation instead of passing them to the generator.

Example fix

# before
openapi-generator-cli generate -g typescript-nestjs \
  -DserviceFileSuffix=_service.ts

# after
openapi-generator-cli generate -g typescript-nestjs \
  -DserviceFileSuffix=.service.ts

Defensive patterns

Strategy: validation

Validate before calling

# in CI before generation
if ! printf '%s' "$SERVICE_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

// TypeScript (build script validating options)
const isValidFileSuffix = (v: string | undefined): boolean =>
  v === undefined || /^[a-zA-Z0-9.-]*$/.test(v);

Try / catch

try {
    org.openapitools.codegen.DefaultGenerator generator = new org.openapitools.codegen.DefaultGenerator();
    generator.opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    // fail the build with the offending option instead of a stack dump
    throw new RuntimeException("Invalid typescript-nestjs suffix option: " + e.getMessage(), e);
}

Prevention

Keep a single naming-convention constant (e.g. '.service') in your build config and reuse it for file suffixes instead of free-text values.
Add a lint step in CI that regex-checks every -D*Suffix value before invoking openapi-generator.
Remember the two regexes: file suffixes allow '.', '-'; class suffixes allow neither.

When it happens

Trigger: Running the generator with -DserviceFileSuffix=_service or -DmodelFileSuffix=_model (underscore is the classic offender), or programmatically via additionalProperties.put("serviceFileSuffix", " my api"). Any value matching [^a-zA-Z0-9.-] triggers it during processOpts.

Common situations: Teams migrating from typescript-angular or NestJS conventions that use snake_case file names (user_service.service.ts); copying suffix values from other generators that allow underscores; YAML/JSON config files where a trailing space or quote slips into the suffix string.

Related errors

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