oracle/graal · error · IllegalStateException

Unexpected end document header

Error message

Unexpected end document header

What it means

ModelBuilder pairs startDocumentHeader/endDocumentHeader; endDocumentHeader throws IllegalStateException('Unexpected end document header') when newProperties is null, i.e. end was called without a preceding successful start (or after the state was already consumed). At the parse level this reflects a malformed stream where a document-property section terminates without being opened, or nested/duplicated header terminators.

Source

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

            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");
        }
        documentLevelProperties = newProperties;
        newProperties = null;
    }

    private GraphDocument resolveDocument(Properties props, Group g) {
        if (rootDocument != null) {
            return rootDocument;
        }
        rootDocument = rootDocumentFactory.documentFor(documentId, props, g);

        if (rootDocument == null) {
            throw new IllegalStateException("Could not find a parent for group " + folder);
        }
        rootDocumentResolved(rootDocument);
        return rootDocument;
    }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. If driving ModelBuilder programmatically, always bracket parseProperties with startDocumentHeader/endDocumentHeader.
2. For parse-time occurrences, regenerate the dump; treat as corruption.
3. Wrap header parsing in try/finally so an exception inside the header cannot leave the builder half-open.

Example fix

// before
builder.endDocumentHeader(); // called without start

// after
builder.startDocumentHeader();
try {
    parseProperties();
} finally {
    builder.endDocumentHeader();
}

builder.startDocumentHeader();
try { parseProperties(); } finally { builder.endDocumentHeader(); }

When it happens

Trigger: A stream whose document-properties section is misaligned so endDocumentHeader runs without startDocumentHeader having set newProperties; duplicated terminators from corrupted bytes; programmatic misuse of the ModelBuilder API by calling endDocumentHeader standalone.

Common situations: Damaged dump files; custom builders/tests driving ModelBuilder directly and mishandling the start/end pairing.

Related errors

• Trying to write during graph print.
• Invalid constant pool index :
• unknown klass type :
• unknown pool type
• Unknown type

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