What causes "Queue filling failed" in apache/iceberg?

Inspect the cause chained to this RuntimeException for the root error.

apache/iceberg · critical · RuntimeException

Queue filling failed

Error message

Queue filling failed

What it means

After the planning loop terminates, planFiles rethrows fillQueueFailedThrowable as "Queue filling failed". The background thread that consumes planned tasks into the queue failed, so the batch cannot be completed even though refresh succeeded.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/AsyncSparkMicroBatchPlanner.java:220

              }
              // end offset may be synthetic and not exist in the queue
              boolean endOffsetSynthetic =
                  currentOffset.snapshotId() == endOffset.snapshotId()
                      && (currentOffset.position() + 1) == endOffset.position();
              shouldTerminate = endOffsetPeek || endOffsetSynthetic;
            } else {
              LOG.trace("planFiles hasn't reached {}, waiting", endOffset);
            }
          } while (!shouldTerminate
              && refreshFailedThrowable == null
              && fillQueueFailedThrowable == null);

          if (refreshFailedThrowable != null) {
            throw new RuntimeException("Table refresh failed", refreshFailedThrowable);
          }

          if (fillQueueFailedThrowable != null) {
            throw new RuntimeException("Queue filling failed", fillQueueFailedThrowable);
          }

          LOG.info(
              "completed planFiles for {}, startOffset: {}, endOffset: {}, files: {}, rows: {}",
              table().name(),
              startOffset,
              endOffset,
              filesInPlan,
              rowsInPlan);
          return result;
        });
  }

  /**
   * This needs to be non destructive on the queue as spark could call this multiple times. Each
   * time, depending on the table state it could return something different
   *
   * @param startOffset the starting offset of the next microbatch

View on GitHub (pinned to 86d9c8fc54)

Solutions

Inspect the cause chained to this RuntimeException for the root error.
Check object store/network errors for the data files being planned.
Ensure the streaming query is not being stopped concurrently with planning.
Restart the query; if reproducible, file/inspect Iceberg issues around the async planner thread pool.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  query.awaitTermination();
} catch (StreamingQueryException e) {
  if (e.getCause() != null && String.valueOf(e.getCause().getMessage()).contains("Queue filling failed")) {
    // inspect the chained cause; restart the stream after resolving IO errors
    restartQueryWithBackoff();
  } else {
    throw e;
  }
}

Prevention

Verify object-store/network stability for data file access.
Avoid stopping the query while a batch is planning.
Alert on this error's chained cause to catch IO regressions early.

When it happens

Trigger: The queue-filling background task throws while iterating planned FileScanTasks (e.g. task reads/opens fail, thread pool rejected, IO error) during planFiles.

Common situations: Object-store errors while accessing data files during planning, executor thread interruption, or bugs in task generation causing the filling thread to die.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/8aca7bcdfbb11129. Report an issue: GitHub.