{"record":{"id":"a776336ac3fac048","repo":"OpenAPITools/openapi-generator","slug":"must-be-a-valid-com-fasterxml-jackson-annotatio","errorCode":null,"errorMessage":"{} must be a valid com.fasterxml.jackson.annotation.JsonInclude.Include value (ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, USE_DEFAULTS, CUSTOM), or NONE to emit no annotation, but was: {}","messagePattern":"(.+?) must be a valid com\\.fasterxml\\.jackson\\.annotation\\.JsonInclude\\.Include value \\(ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, USE_DEFAULTS, CUSTOM\\), or NONE to emit no annotation, but was: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonAnnotationPolicyUtils.java","lineNumber":84,"sourceCode":"\n    private JsonAnnotationPolicyUtils() {\n    }\n\n    /**\n     * Validate and normalize a manual per-property {@code x-jackson-json-include-policy} override.\n     *\n     * @param rawPolicy       the raw vendor extension value set directly on the property in the spec\n     * @param extensionName   the vendor extension key, used in the error message (kept generator-agnostic)\n     * @return the normalized (upper-case) policy name to emit, or {@code null} when the override means\n     * \"emit no annotation\" ({@code NONE}/blank), in which case the caller must drop the extension.\n     * @throws IllegalArgumentException when the override is not a valid {@code JsonInclude.Include} value.\n     */\n    public static String resolveManualJsonIncludePolicy(Object rawPolicy, String extensionName) {\n        JsonIncludePolicy parsed;\n        try {\n            parsed = JsonIncludePolicy.parse(rawPolicy);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(extensionName\n                    + \" must be a valid com.fasterxml.jackson.annotation.JsonInclude.Include value \"\n                    + \"(ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, USE_DEFAULTS, CUSTOM), or NONE to emit \"\n                    + \"no annotation, but was: \" + rawPolicy);\n        }\n        if (parsed == null || !parsed.isEmitted()) {\n            return null;\n        }\n        return parsed.name();\n    }\n\n    /**\n     * Validate and normalize the {@code optionalNonNullPropertyJsonInclude} config option value.\n     *\n     * @param policy      the raw config option value (may be {@code null}, in which case the default\n     *                    {@code NON_NULL} is returned)\n     * @param optionName  the config option name, used in the error message (kept generator-agnostic)\n     * @return the normalized (upper-case) policy name: one of {@code NON_NULL}, {@code NON_EMPTY},\n     * {@code NON_DEFAULT}, {@code NONE}.","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/JsonAnnotationPolicyUtils.java#L66-L102","documentation":"JsonAnnotationPolicyUtils.resolveManualJsonIncludePolicy (used by the spring and kotlin-spring generators) validates a per-property 'x-jackson-json-include-policy' vendor extension from the spec. The value must be a Jackson JsonInclude.Include constant — ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, USE_DEFAULTS, CUSTOM — or NONE/blank meaning 'emit no annotation'. Anything else throws IllegalArgumentException, with the extension name prefixed so you know where to look.","triggerScenarios":"Adding x-jackson-json-include-policy: non-null (hyphen instead of underscore), if_present, or NEVER to a schema property in the OpenAPI spec and generating with -g spring or -g kotlin-spring. Values are matched case-insensitively after trim, but only exact enum names parse.","commonSituations":"Writing Jackson annotation values from memory with hyphens or wrong casing of words ('non-null', 'use-defaults'); copying Jackson 2.x vs 3.x enum names; a misspelled extension value silently present in a large spec until generation fails.","solutions":["Use an exact JsonInclude.Include enum name in the spec: NON_NULL, NON_EMPTY, NON_DEFAULT, ALWAYS, NON_ABSENT, USE_DEFAULTS, CUSTOM (underscores, case-insensitive).","Use NONE or an empty value when you want no @JsonInclude emitted for that property.","Search your spec for x-jackson-json-include-policy and validate each occurrence against the enum list in the error message."],"exampleFix":"# before (openapi.yaml)\ncomponents:\n  schemas:\n    User:\n      properties:\n        email:\n          type: string\n          x-jackson-json-include-policy: non-null\n\n# after\n          x-jackson-json-include-policy: NON_NULL","handlingStrategy":"validation","validationCode":"// Node: validate x-jackson-json-include-policy values in the spec\nconst ALLOWED = new Set(['ALWAYS','NON_NULL','NON_ABSENT','NON_EMPTY','NON_DEFAULT','USE_DEFAULTS','CUSTOM','NONE','']);\nconst check = (o) => { for (const [k, v] of Object.entries(o ?? {})) {\n  if (k === 'x-jackson-json-include-policy' && !ALLOWED.has(String(v).trim().toUpperCase()))\n    throw new Error(`invalid x-jackson-json-include-policy: ${v}`);\n  if (v && typeof v === 'object') check(v);\n}};\ncheck(require('./openapi.json'));","typeGuard":"const JSON_INCLUDE_POLICIES = ['ALWAYS','NON_NULL','NON_ABSENT','NON_EMPTY','NON_DEFAULT','USE_DEFAULTS','CUSTOM','NONE'] as const;\ntype JsonIncludePolicy = typeof JSON_INCLUDE_POLICIES[number];\nconst isJsonIncludePolicy = (v: unknown): v is JsonIncludePolicy =>\n  typeof v === 'string' &&\n  (JSON_INCLUDE_POLICIES as readonly string[]).includes(v.trim().toUpperCase());","tryCatchPattern":"catch (IllegalArgumentException e) {\n    // message names the extension and the bad value — fix the spec and regenerate\n    throw new RuntimeException(\"Spec fix needed: \" + e.getMessage(), e);\n}","preventionTips":["Use exact JsonInclude.Include enum names with underscores; case-insensitive but not hyphen-tolerant.","Keep a snippet/cheat-sheet of allowed extension values next to your spec linting config."],"tags":["jackson","spring","vendor-extension","codegen","validation"],"backgroundTag":"invalid-vendor-extension-value","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}