OpenAPITools/openapi-generator · error · IllegalArgumentException

Unreferenced enum {hash}

Error message

Unreferenced enum {hash}

What it means

The OCaml generator pre-registers every enum it knows about: collectEnumSchemas() walks components.schemas and each operation's parameters, then computeEnumUniqNames() assigns each distinct enum value-set an OCaml name, stored in enumUniqNames keyed by the set of values. Later, toEnumName() looks up property.get_enum() in that registry and throws 'Unreferenced enum' (OCamlClientCodegen.java:932) when the value-set was never registered — i.e. the enum lives somewhere collectEnumSchemas() does not walk.

Source

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

    }

    @Override
    public String escapeUnsafeCharacters(String input) {
        return input
                .replace("*)", "*_)")
                .replace("(*", "(_*")
                .replace("\"", "''");
    }

    @Override
    public String toEnumName(CodegenProperty property) {
        Set<String> hash = new TreeSet<>(property.get_enum());

        if (enumUniqNames.containsKey(hash)) {
            return enumUniqNames.get(hash);
        }

        throw new IllegalArgumentException("Unreferenced enum " + hash);
    }

    @Override
    public String toDefaultValue(Schema p) {
        if (p.getDefault() != null) {
            if (p.getEnum() != null) {
                return ocamlizeEnumValue(p.getDefault().toString());
            }
            return p.getDefault().toString();
        } else {
            return null;
        }
    }

    @Override
    public void postProcessFile(File file, String fileType) {
        super.postProcessFile(file, fileType);

View on GitHub (pinned to fcec517be3)

Solutions

1. Hoist the offending enum into components/schemas and reference it via $ref from the response/requestBody/property.
2. Or move the enum inline into an operation parameter schema, which the collector does walk.
3. Upgrade openapi-generator — enum collection coverage in the OCaml generator has been patched over time; if the shape is valid OpenAPI, file an issue with the spec.

Example fix

# before (inline enum in a response)
paths:
  /status:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
                enum: [ready, busy]
# after (named component enum)
paths:
  /status:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    Status:
      type: string
      enum: [ready, busy]

// ocaml: verify every enum in the spec is reachable from walked locations
// (components.schemas and operation parameters); hoist inline response/requestBody enums.
Set<Set<String>> declared = new HashSet<>();
openAPI.getComponents().getSchemas().values().forEach(s -> {
  if (s.getEnum() != null) declared.add(new TreeSet<>(s.getEnum().stream().map(String::valueOf).toList()));
});
// walk responses/requestBodies for inline enums not in `declared` and report them
for (var path : openAPI.getPaths().values()) {
  for (Operation op : path.readOperations().values()) {
    if (op.getResponses() == null) continue;
    for (ApiResponse r : op.getResponses().values()) {
      if (r.getContent() == null) continue;
      for (MediaType mt : r.getContent().values()) {
        Schema<?> s = mt.getSchema();
        if (s != null && s.getEnum() != null
            && !declared.contains(new TreeSet<>(s.getEnum().stream().map(String::valueOf).toList()))) {
          throw new IllegalArgumentException("Inline enum in response of " + op.getOperationId()
              + " must be hoisted to components/schemas for the ocaml generator");
        }
      }
    }
  }
}

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    // message prints the unregistered enum value-set; find it in the spec and hoist to components
    throw new BuildException("OCaml generation failed: " + e.getMessage(), e);
}

When it happens

Trigger: Generating with `-g ocaml` from a spec that declares an enum inline in a location the collector misses — e.g. inline in a response schema, a requestBody schema, or a nested inline object — so the model contains an enum value-set absent from enumUniqNames when toEnumName() runs.

Common situations: Specs that use inline enums instead of named component schemas; converting a spec from another generator workflow where inline enums were tolerated; adding response examples with inline enum constraints after the initial component-based design.

Related errors

• The BLOB and JSON data types cannot be assigned a default va
• Empty database/table/column name for property '{name}' not a
• The BLOB, TEXT, GEOMETRY, and JSON data types cannot be assi
• Empty database/table/column name for property '{name}' not a
• Empty method name (operationId) not allowed

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