OpenAPITools/openapi-generator · error · RuntimeException

Word '${name}' could not be escaped.

Error message

Word '${name}' could not be escaped.

What it means

StringUtils.escape (line 262) maps each character of a name through a replacement map and joins the results. The reduce(...).orElse(null) yields null only when the input's chars() stream is empty — i.e. the name is an empty string — at which point the RuntimeException 'Word ... could not be escaped.' is thrown. So despite the generic wording, this error means escape("") was called: some generator passed an empty identifier (model/property/operation name) into escaping.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/StringUtils.java:278

     * throws Runtime exception as word is not escaped properly.
     */
    public static String escape(final String name, final Map<String, String> replacementMap,
                                final List<String> charactersToAllow, final String appendToReplacement) {
        EscapedNameOptions ns = new EscapedNameOptions(name, replacementMap.keySet(), charactersToAllow, appendToReplacement);
        return escapedWordsCache.get(ns, wordToEscape -> {
            String result = name.chars().mapToObj(c -> {
                String character = String.valueOf((char) c);
                if (charactersToAllow != null && charactersToAllow.contains(character)) {
                    return character;
                } else if (replacementMap.containsKey(character)) {
                    return replacementMap.get(character) + (appendToReplacement != null ? appendToReplacement : "");
                } else {
                    return character;
                }
            }).reduce((c1, c2) -> c1 + c2).orElse(null);

            if (result != null) return result;
            throw new RuntimeException("Word '" + name + "' could not be escaped.");
        });
    }

    /**
     * Return a unique string based on a set of processed strings.
     *
     * @param processedStrings a set of strings that have been processed
     * @param input            input to be checked for uniqueness
     * @return a unique string
     */
    public static String getUniqueString(Set<String> processedStrings, String input) {
        if (input == null) {
            return null;
        }

        String uniqueName = input;
        // check for input uniqueness
        int counter = 0;

View on GitHub (pinned to fcec517be3)

Solutions

  1. Find what is empty: the exception shows Word '' — inspect the stack trace for the calling generator method and check the corresponding spec element (property name, tag, operationId) near the failing model.
  2. Give every schema property, definition and operation a non-empty, alphanumeric-starting name in the spec.
  3. In custom code calling escape, guard empty inputs and fall back to a sensible default name instead of escaping "".

Example fix

// before (custom code)
String className = StringUtils.escape(schemaName, replacements, allowed, "_");
// schemaName may be "" for anonymous schemas

// after
String className = StringUtils.escape(
    schemaName == null || schemaName.isEmpty() ? "GeneratedModel" : schemaName,
    replacements, allowed, "_");
Defensive patterns

Strategy: validation

Validate before calling

// Node: reject empty names anywhere in the spec before generating
const check = (o, path) => { for (const [k, v] of Object.entries(o ?? {})) {
  if (/^(properties|schemas|operationId|tag)$/.test(k) || path === 'properties') {
    if ((k === '' || k === 'operationId') && String(v).length === 0)
      throw new Error('empty identifier in spec');
  }
  if (v && typeof v === 'object') check(v, k);
}};
check(require('./openapi.json'), '');

Type guard

// Java: guard before calling StringUtils.escape
String safeEscape(String name) {
    return StringUtils.escape(
        (name == null || name.isEmpty()) ? "Generated" : name,
        replacements, allowed, "_");
}

Prevention

When it happens

Trigger: A generator or plugin calling StringUtils.escape with an empty string, e.g. a schema with an empty-name property, an empty tag or operationId-derived value, or code that builds names by string concatenation and produces "" before escaping. The message renders as: Word '' could not be escaped.

Common situations: Specs with anonymous/empty property names ("": {type: string}) that some tools tolerate; custom template code or third-party generator subclasses constructing names from optional vendor extensions that are absent; edge cases after name sanitization strips everything.

Related errors

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