apache/flink · error · java.lang.IllegalArgumentException

Cyclic references are not supported

Error message

Cyclic references are not supported:{}

What it means

Fires when resolving a '$ref' leads back to a node already being converted, i.e. the schema contains a reference cycle. Recursive schemas have no finite row representation in Flink's type system, so the converter aborts and reports the cycling reference path.

Solutions

1. Address the cause reported by the error message: Cyclic references are not supported:the reported value
2. Verify the inputs, configuration values, and classpath/dependency setup related to this operation, then retry.

Example fix

Correct the condition described ("Cyclic references are not supported:the reported value") and rerun the job or command.

When it happens

Trigger: Triggered at runtime when the operation fails because: Cyclic references are not supported:the reported value.

Common situations: Commonly caused by misconfiguration, missing dependencies or files, unsupported types or operations, or invalid user input leading to: Cyclic references are not supported:the reported value.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/18122d4e3c68ac90. Report an issue: GitHub.

Appendix: source

Thrown at flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonRowSchemaConverter.java:364

                        "Invalid encoding '" + node.asText() + "' in node: " + location);
        }
    }

    private static JsonNode resolveReference(String ref, JsonNode origin, JsonNode root) {
        if (!ref.startsWith("#")) {
            throw new IllegalArgumentException(
                    "Only JSON schemes with simple references "
                            + "(one indirection in the same document) are supported yet. But was: "
                            + ref);
        }
        final String path = ref.substring(1);
        final JsonNode foundNode = root.at(path);
        if (foundNode.isMissingNode()) {
            throw new IllegalArgumentException("Could not find reference: " + ref);
        }
        // prevent obvious cyclic references
        if (foundNode == origin) {
            throw new IllegalArgumentException("Cyclic references are not supported:" + ref);
        }
        return foundNode;
    }

    private static TypeInformation<?>[] convertTypes(
            String location, JsonNode arrayNode, JsonNode root) {
        final TypeInformation<?>[] types = new TypeInformation[arrayNode.size()];
        final Iterator<JsonNode> elements = arrayNode.elements();
        int i = 0;
        while (elements.hasNext()) {
            final TypeInformation<?> elementType =
                    convertType(location + '[' + i + ']', elements.next(), root);
            types[i] = elementType;
            i += 1;
        }
        return types;
    }
}

View on GitHub (pinned to 2f3c205e92)