What causes "recursionLimit must be an integer, e.g. 2000." in OpenAPITools/openapi-generator?

Pass a plain integer string: -c recursionLimit=2000

OpenAPITools/openapi-generator · error · IllegalArgumentException

recursionLimit must be an integer, e.g. 2000.

Error message

recursionLimit must be an integer, e.g. 2000.

What it means

The python-pydantic-v1 generator (Pydantic 1.x models) accepts the same recursionLimit option as the main python generator, and validates it identically in processOpts(): the value must be a String parseable by Integer.parseInt, otherwise IllegalArgumentException('recursionLimit must be an integer, e.g. 2000.') is thrown before generation.

Source

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

            testFolder = packagePath() + File.separatorChar + testFolder;
            // api/model docs in <package>/docs
            apiDocPath = packagePath() + "/" + apiDocPath;
            modelDocPath = packagePath() + "/" + modelDocPath;
        }
        // make api and model doc path available in mustache template
        additionalProperties.put("apiDocPath", apiDocPath);
        additionalProperties.put("modelDocPath", modelDocPath);

        if (additionalProperties.containsKey(PACKAGE_URL)) {
            setPackageUrl((String) additionalProperties.get(PACKAGE_URL));
        }

        // check to see if setRecursionLimit is set and whether it's an integer
        if (additionalProperties.containsKey(RECURSION_LIMIT)) {
            try {
                Integer.parseInt((String) additionalProperties.get(RECURSION_LIMIT));
            } catch (NumberFormatException | NullPointerException e) {
                throw new IllegalArgumentException("recursionLimit must be an integer, e.g. 2000.");
            }
        }

        if (additionalProperties.containsKey(CodegenConstants.USE_ONEOF_DISCRIMINATOR_LOOKUP)) {
            setUseOneOfDiscriminatorLookup(convertPropertyToBooleanAndWriteBack(CodegenConstants.USE_ONEOF_DISCRIMINATOR_LOOKUP));
        } else {
            additionalProperties.put(CodegenConstants.USE_ONEOF_DISCRIMINATOR_LOOKUP, useOneOfDiscriminatorLookup);
        }

        if (additionalProperties.containsKey(MAP_NUMBER_TO)) {
            setMapNumberTo(String.valueOf(additionalProperties.get(MAP_NUMBER_TO)));
        }

        if (additionalProperties.containsKey(DATETIME_FORMAT)) {
            setDatetimeFormat((String) additionalProperties.get(DATETIME_FORMAT));
        } else {
            additionalProperties.put(DATETIME_FORMAT, datetimeFormat);
        }

View on GitHub (pinned to fcec517be3)

Solutions

Pass a plain integer string: -c recursionLimit=2000
Guard CI templates: ${RECURSION_LIMIT:-2000} so an unset variable never yields an empty value
Remove the option if the default recursion limit is acceptable
If setting programmatically, put a String value, not a boxed numeric

Example fix

# before
openapi-generator-cli generate -i api.yaml -g python-pydantic-v1 -c recursionLimit=1e4
# after
openapi-generator-cli generate -i api.yaml -g python-pydantic-v1 -c recursionLimit=10000

Defensive patterns

Strategy: validation

Validate before calling

# bash
[[ "${RECURSION_LIMIT:-}" =~ ^-?[0-9]+$ ]] || unset RECURSION_LIMIT  # let the generator default apply
openapi-generator-cli generate -i api.yaml -g python-pydantic-v1 ${RECURSION_LIMIT:+-c recursionLimit=$RECURSION_LIMIT}

Try / catch

try {
    codegen.additionalProperties().put("recursionLimit", "2000"); // integer string only
    new DefaultGenerator().opts(input).generate();
} catch (IllegalArgumentException e) {
    // 'recursionLimit must be an integer' - correct the value and rerun; nothing was partially generated
}

Prevention

Use a plain integer string for recursionLimit on python-pydantic-v1
Share one canonical config snippet for the option across python and python-pydantic-v1 jobs
Skip the option entirely when the default limit is sufficient

When it happens

Trigger: openapi-generator-cli generate -g python-pydantic-v1 -c recursionLimit=high / recursionLimit=100.5 / recursionLimit='' ; or plugin/maven config with a non-integer value.

Common situations: Reusing a working python-generator config against -g python-pydantic-v1 after someone 'fixed' the value into a float or word; CI templating that injects an empty default when the variable is unset.

Related errors

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