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 generator accepts a recursionLimit additional-property that ends up as sys.setrecursionlimit() in the generated client. During processOpts() the value is cast to String and passed to Integer.parseInt; anything that is not a base-10 integer string throws IllegalArgumentException('recursionLimit must be an integer, e.g. 2000.') before any file is written.

Source

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

        }
        // make api and model doc path available in mustache template
        additionalProperties.put("apiDocPath", apiDocPath);
        additionalProperties.put("modelDocPath", modelDocPath);

        if (additionalProperties.containsKey(SET_ENSURE_ASCII_TO_FALSE)) {
            additionalProperties.put(SET_ENSURE_ASCII_TO_FALSE, Boolean.valueOf(additionalProperties.get(SET_ENSURE_ASCII_TO_FALSE).toString()));
        }

        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
In Maven/Gradle plugin config use <recursionLimit>2000</recursionLimit> with no quotes, spaces, or separators
If setting programmatically, put a String: additionalProperties.put('recursionLimit', String.valueOf(2000))
If you do not actually need it, remove the option entirely (it is optional)

Example fix

# before
openapi-generator-cli generate -i api.yaml -g python -c recursionLimit=3_000
# after
openapi-generator-cli generate -i api.yaml -g python -c recursionLimit=3000

Defensive patterns

Strategy: validation

Validate before calling

# bash: validate before running the generator
[[ "${RECURSION_LIMIT:-}" =~ ^[0-9]+$ ]] || RECURSION_LIMIT=2000
openapi-generator-cli generate -i api.yaml -g python -c recursionLimit=${RECURSION_LIMIT}

Try / catch

try {
    PythonClientCodegen codegen = new PythonClientCodegen();
    codegen.additionalProperties().put("recursionLimit", String.valueOf(2000)); // always a String
    new DefaultGenerator().opts(new ClientOptInput().opts(codegen)).generate();
} catch (IllegalArgumentException e) {
    // message names the offending option; fix the value and rerun, do not retry blindly
}

Prevention

Always pass recursionLimit as a plain integer string with no separators or units
Template CI variables with a numeric default: ${RECURSION_LIMIT:-2000}
When configuring programmatically, put String.valueOf(int), never a boxed type

When it happens

Trigger: openapi-generator-cli generate -g python -c recursionLimit=20.00 / recursionLimit=true / recursionLimit='' ; or a Maven/Gradle/plugin config where <recursionLimit>2_000</recursionLimit> is used. The value must arrive as a string like 2000.

Common situations: Copy-pasting the option with a unit, a decimal, or a thousands separator; YAML configs that coerce the value to a boolean or leave it empty; scripts templating the flag from an unset environment variable producing an empty string.

Related errors

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