oracle/graal · error · IllegalStateException

Document header not at root level.

Error message

Document header not at root level.

What it means

ModelBuilder.startDocumentHeader implements the rule that document (stream) properties may only appear at the top level of a dump: the current parent folder must be the GraphDocument itself or null. If a STREAM_PROPERTIES entry is encountered while a group is open (parent is a Group), IllegalStateException('Document header not at root level.') is thrown, because a conforming writer never nests stream properties inside a group.

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/graphio/parsing/ModelBuilder.java:549

        return g;
    }

    @Override
    public Group startGroup() {
        Group group = createGroup(folder);
        return pushGroup(group, true);
    }

    protected void rootDocumentResolved(GraphDocument doc) {
        this.rootDocument = doc;
    }

    @Override
    public void startDocumentHeader() {
        Folder f = getParent();
        if (f != null) {
            if (!(f instanceof GraphDocument)) {
                throw new IllegalStateException("Document header not at root level.");
            }
            newProperties = ((GraphDocument) f).getProperties();
        } else {
            // note: if there are more document headers in the stream,
            // the last property value wins. All document-level property sets merge in the result.
            if (rootDocument == null) {
                newProperties = Properties.newProperties();
            } else {
                newProperties = rootDocument.getProperties();
            }
        }
    }

    @Override
    public void endDocumentHeader() {
        if (newProperties == null) {
            throw new IllegalStateException("Unexpected end document header");
        }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Re-dump the file with a stock producer (document properties are written before any group in a conforming stream).
2. If writing a custom producer, emit STREAM_PROPERTIES only at the root, before any BEGIN_GROUP.
3. Treat the message as evidence of stream damage and verify integrity/versions.

try { reader.parse(); } catch (IllegalStateException e) { if (e.getMessage().contains("Document header not at root level")) { /* malformed nesting: regenerate dump */ } }

When it happens

Trigger: A stream in which STREAM_PROPERTIES appears after BEGIN_GROUP but before CLOSE_GROUP; corrupted nesting that leaves a group open; custom writers emitting document properties at the wrong nesting point.

Common situations: Malformed or hand-assembled dumps; producer bugs that write document properties lazily after the first group has started; damaged files.

Related errors

• Invalid constant pool index :
• unknown klass type :
• unknown pool type
• Unknown type
• File header is missing

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/fd6d3e0c15a7f1ed. Report an issue: GitHub.