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

Restrict the suffix to alphanumerics, '.' and '-' (e.g. -DserviceFileSuffix=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 Angular generator validates file-suffix options (serviceFileSuffix, modelFileSuffix) with a pattern allowing only '.', '-' and alphanumeric characters, because the suffix becomes part of file names. The check runs during option processing; any other character (underscore, space, slash, dot-leading paths) aborts generation.

Source

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

            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 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)
            );
        }

View on GitHub (pinned to fcec517be3)

Solutions

Restrict the suffix to alphanumerics, '.' and '-' (e.g. -DserviceFileSuffix=Service).
Drop the suffix option entirely to use the generator default.
Use output/library options (apiPackage, modelPackage) for directory placement, not the file suffix.

Example fix

# before
-DserviceFileSuffix=_service

# after
-DserviceFileSuffix=Service

Defensive patterns

Strategy: validation

Validate before calling

// node: validate suffix options against the generator's pattern
const FILE_SUFFIX = /^[A-Za-z0-9.-]+$/;
const assertSuffix = (name, v) => { if (!FILE_SUFFIX.test(v)) throw new Error(`${name} invalid: ${v}`); };
assertSuffix('serviceFileSuffix', opts.serviceFileSuffix ?? 'Service');
assertSuffix('modelFileSuffix', opts.modelFileSuffix ?? 'Model');

Type guard

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

Try / catch

// Java
try { new DefaultGenerator().opts(input).generate(); }
catch (IllegalArgumentException e) {
    // strip illegal characters from suffix options and rerun
}

Prevention

Remember suffixes name files: alphanumerics, '.' and '-' only.
Validate naming options in a pre-flight check shared by all generation jobs.
Use package options for directory structure instead of suffix hacks.

When it happens

Trigger: -DserviceFileSuffix=_service or -DmodelFileSuffix=.gen/models — any suffix containing characters outside [A-Za-z0-9.-].

Common situations: Using snake_case suffixes out of habit; trying to smuggle a subdirectory into the suffix; copying suffix conventions from other generators that are more permissive.

Related errors

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