prestodb/presto · error · java.lang.IllegalStateException

Declared positions (%s) does not match block %s's number of

Error message

Declared positions (%s) does not match block %s's number of entries (%s)

What it means

PageBuilder.build() finalizes all column block builders into a Page. It throws this IllegalStateException if any built block's position count differs from declaredPositions (the row count the builder tracked when rows were begun), because all channels in a page must contain the same number of entries. This usually means some column builders received more or fewer values than others.

Source

Thrown at presto-common/src/main/java/com/facebook/presto/common/PageBuilder.java:168

        // as it has much better performance.
        long retainedSizeInBytes = 0;
        for (BlockBuilder blockBuilder : blockBuilders) {
            retainedSizeInBytes += blockBuilder.getRetainedSizeInBytes();
        }
        return retainedSizeInBytes;
    }

    public Page build()
    {
        if (blockBuilders.length == 0) {
            return new Page(declaredPositions);
        }

        Block[] blocks = new Block[blockBuilders.length];
        for (int i = 0; i < blocks.length; i++) {
            blocks[i] = blockBuilders[i].build();
            if (blocks[i].getPositionCount() != declaredPositions) {
                throw new IllegalStateException(String.format("Declared positions (%s) does not match block %s's number of entries (%s)", declaredPositions, i, blocks[i].getPositionCount()));
            }
        }

        return Page.wrapBlocksWithoutCopy(declaredPositions, blocks);
    }

    private static void checkArgument(boolean expression, String errorMessage)
    {
        if (!expression) {
            throw new IllegalArgumentException(errorMessage);
        }
    }
}

View on GitHub (pinned to 55bb57d202)

Solutions

Audit the code between declarePosition() (or row start) and build(): every column builder must receive exactly one value (or null via appendNull) per declared row.
Call pageBuilder.reset() or build() only at consistent row boundaries; never call build() while a row is partially written.
For skipped rows, explicitly call appendNull() on every column builder that did not get a value.
Add a debug assertion comparing each blockBuilder.getPositionCount() before build() to find which column diverges.

Example fix

// before
pageBuilder.declarePosition();
columnBuilderA.writeLong(value);
// forgot to write columnBuilderB
Page page = pageBuilder.build(); // IllegalStateException
// after
pageBuilder.declarePosition();
columnBuilderA.writeLong(value);
if (value == null) { columnBuilderB.appendNull(); } else { columnBuilderB.writeLong(value); }
Page page = pageBuilder.build();

Defensive patterns

Strategy: validation

Validate before calling

for (BlockBuilder builder : pageBuilder.getBlockBuilders()) {
    if (builder.getPositionCount() != expectedRows) {
        throw new IllegalStateException("column builder row count mismatch: "
            + builder.getPositionCount() + " != " + expectedRows);
    }
}
Page page = pageBuilder.build();

Try / catch

try {
    Page page = pageBuilder.build();
} catch (IllegalStateException e) {
    pageBuilder.reset();
    throw new IllegalStateException("incomplete row written to PageBuilder; page discarded", e);
}

Prevention

Write exactly one value or appendNull() to every column builder per declarePosition().
Never call build() in the middle of writing a row.
Use pageBuilder.reset() when aborting a partially written page.
Log per-builder position counts when a mismatch occurs to locate the offending column.

When it happens

Trigger: Calling pageBuilder.build() after writing a different number of values to different column builders since the last build()/declarePosition() — e.g. appending to one block builder but forgetting another, or calling build() mid-row.

Common situations: Operator output code where a conditional branch skips writing a value for one column; writing N values for a nested/array-typed column while other columns got a different count; forgetting to reset/rebuild builders consistently across pages.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/3777334b25b142e1. Report an issue: GitHub.