apache/flink · critical · FlinkException

Triggering a detached savepoint for the job {} failed.

Error message

Triggering a detached savepoint for the job {} failed.

What it means

Thrown from NestedPrimitiveColumnReader.initDataReader when a nested column's page is dictionary-encoded but the reader has no dictionary — the dictionary page was absent or failed earlier. This is the nested-reader equivalent of the flat reader's 'dictionary was missing' error: the page metadata promises dictionary ids but there is no dictionary to resolve them against.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/cli/CliFrontend.java:900

    private void triggerDetachedSavepoint(
            ClusterClient<?> clusterClient,
            JobID jobId,
            String savepointDirectory,
            SavepointFormatType formatType,
            Duration clientTimeout)
            throws FlinkException {
        logAndSysout("Triggering savepoint in detached mode for job " + jobId + '.');

        try {
            final String triggerId =
                    clusterClient
                            .triggerDetachedSavepoint(jobId, savepointDirectory, formatType)
                            .get(clientTimeout.toMillis(), TimeUnit.MILLISECONDS);

            logAndSysout("Successfully trigger manual savepoint, triggerId: " + triggerId);
        } catch (Exception e) {
            Throwable cause = ExceptionUtils.stripExecutionException(e);
            throw new FlinkException(
                    "Triggering a detached savepoint for the job " + jobId + " failed.", cause);
        }
    }

    /** Sends a SavepointDisposalRequest to the job manager. */
    private void disposeSavepoint(
            ClusterClient<?> clusterClient, String savepointPath, Duration clientTimeout)
            throws FlinkException {
        checkNotNull(
                savepointPath,
                "Missing required argument: savepoint path. "
                        + "Usage: bin/flink savepoint -d <savepoint-path>");

        logAndSysout("Disposing savepoint '" + savepointPath + "'.");

        final CompletableFuture<Acknowledge> disposeFuture =
                clusterClient.disposeSavepoint(savepointPath);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify with `parquet-tools meta` that dictionary-encoded pages in that column chunk are preceded by a dictionary page
2. Re-obtain/regenerate the file; a dictionary-encoded page without a dictionary page is invalid Parquet
3. If using a custom ParquetReaderFactory/PageReader supplier, ensure readDictionaryPage() returns the chunk's dictionary page before data pages
4. Rewrite the file with a standard writer as a workaround

// With parquet-mr, confirm the dictionary page exists for dictionary-encoded chunks
try (ParquetFileReader r = ParquetFileReader.open(conf, path)) {
    PageReadStore rowGroup = r.readNextRowGroup();
    for (ColumnChunkMetaData cc : rowGroup.getRowGroups().get(0).getColumns()) {
        boolean needsDict = cc.getEncodings().stream().anyMatch(Encoding::usesDictionary);
        // parquet-mr delivers it via ParquetFileReader; a missing dict page makes
        // readDictionaryPage() return null — flag the file before vectorized reading
    }
}

try {
    nestedReader.readAndNewVector(...);
} catch (IOException e) {
    if (String.valueOf(e.getMessage()).contains("dictionary was missing")) {
        quarantine(file); // deterministic
    } else throw e;
}

When it happens

Trigger: initDictionaryPage ran when pageReader.readDictionaryPage() returned null (or its try block set nothing), and later pages are dictionary-encoded; malformed column chunks omitting the dictionary page; PageReader implementations that skip dictionary pages.

Common situations: Corrupt or non-standard files from exotic writers; row groups where dictionary overflow fallback was handled incorrectly by the writer; custom PageReaders (e.g. in iceberg/hoodie-style stacks) that mis-handle dictionary pages.

Related errors

• Missing JobID. Specify a Job ID to trigger a savepoint.
• Translator {} cannot translate the given pipeline {}.
• Could not stop with a detached savepoint job "{}".
• Failed to dispose the savepoint '{}'.
• Missing JobID. Specify a Job ID to manipulate a checkpoint.

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