{"record":{"id":"a6ea6026576b08ae","repo":"apache/beam","slug":"retrieving-successful-inserts-is-only-supported-for","errorCode":null,"errorMessage":"Retrieving successful inserts is only supported for streaming inserts. Make sure withSuccessfulInsertsPropagation is correctly configured for BigQueryIO.Write object.","messagePattern":"Retrieving successful inserts is only supported for streaming inserts\\. Make sure withSuccessfulInsertsPropagation is correctly configured for BigQueryIO\\.Write object\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/WriteResult.java","lineNumber":165,"sourceCode":"   */\n  public PCollection<TableDestination> getSuccessfulTableLoads() {\n    Preconditions.checkArgumentNotNull(\n        successfulBatchInsertsTag,\n        \"Cannot use getSuccessfulTableLoads because this WriteResult was not \"\n            + \"configured to produce them.  Note: only batch loads produce successfulTableLoads.\");\n    return Preconditions.checkArgumentNotNull(\n        successfulBatchInserts,\n        \"Cannot use getSuccessfulTableLoads because this WriteResult was not \"\n            + \"configured to produce them.  Note: only batch loads produce successfulTableLoads.\");\n  }\n\n  /**\n   * Returns a {@link PCollection} containing the {@link TableRow}s that were written to BQ via the\n   * streaming insert API.\n   */\n  public PCollection<TableRow> getSuccessfulInserts() {\n    if (successfulInserts == null) {\n      throw new IllegalStateException(\n          \"Retrieving successful inserts is only supported for streaming inserts. \"\n              + \"Make sure withSuccessfulInsertsPropagation is correctly configured for \"\n              + \"BigQueryIO.Write object.\");\n    }\n    return successfulInserts;\n  }\n\n  /**\n   * Returns a {@link PCollection} containing the {@link TableRow}s that didn't make it to BQ.\n   *\n   * <p>Only use this method if you haven't enabled {@link\n   * BigQueryIO.Write#withExtendedErrorInfo()}. Otherwise use {@link\n   * WriteResult#getFailedInsertsWithErr()}\n   */\n  public PCollection<TableRow> getFailedInserts() {\n    Preconditions.checkArgumentNotNull(\n        failedInsertsTag,\n        \"Cannot use getFailedInserts as this WriteResult uses extended errors\"","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/WriteResult.java#L147-L183","documentation":"WriteResult.getSuccessfulInserts returns the PCollection of TableRows successfully inserted via the BigQuery streaming insert API. That collection only exists when the write was configured with withSuccessfulInsertsPropagation(); for batch loads or when propagation isn't enabled, it is null and the method throws this IllegalStateException.","triggerScenarios":"Calling writeResult.getSuccessfulInserts() after a BigQueryIO.Write that was built without .withSuccessfulInsertsPropagation(), or on a batch (FILE_LOADS / STORAGE_API_WRITES) write.","commonSituations":"Developers switch from streaming inserts to batch loads and keep the getSuccessfulInserts call; forgetting the flag when constructing the Write transform; copying example code that assumed streaming inserts.","solutions":["Add .withSuccessfulInsertsPropagation() to your BigQueryIO.Write transform and use streaming inserts (withMethod(Write.Method.STREAMING_INSERTS)).","If you switched to batch loads, stop calling getSuccessfulInserts — batch loads don't produce per-row insert results; handle job-level errors instead.","Guard the call: only read successful inserts when your write method is STREAMING_INSERTS and the flag was set."],"exampleFix":"// before\nWriteResult result = table.apply(\"write\", BigQueryIO.writeTableRows().to(spec).withTemplateCompatibility());\nPCollection<TableRow> ok = result.getSuccessfulInserts(); // throws\n// after\nWriteResult result = table.apply(\"write\", BigQueryIO.writeTableRows().to(spec)\n    .withMethod(Write.Method.STREAMING_INSERTS)\n    .withSuccessfulInsertsPropagation());\nPCollection<TableRow> ok = result.getSuccessfulInserts();","handlingStrategy":"validation","validationCode":"if (writeMethod == Write.Method.STREAMING_INSERTS && insertPropagationEnabled) {\n  PCollection<TableRow> ok = result.getSuccessfulInserts();\n}","typeGuard":null,"tryCatchPattern":"try { return result.getSuccessfulInserts(); } catch (IllegalStateException e) { log.warn(\"No successful-inserts collection; batch write?\", e); return null; }","preventionTips":["Always pair withSuccessfulInsertsPropagation() with STREAMING_INSERTS method.","Encapsulate write configuration in one factory so flags and getters stay consistent.","Check WriteResult.getFailedInserts vs getSuccessfulInserts applicability per method."],"tags":["bigquery","streaming-inserts","api-misuse"],"backgroundTag":"invalid-state-transition","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}