{"record":{"id":"6243cf7550c25ec1","repo":"apache/beam","slug":"the-use-native-datetime-parameter-cannot-be-true-for-export","errorCode":null,"errorMessage":"The \"use_native_datetime\" parameter cannot be True for EXPORT. Please set the \"use_native_datetime\" parameter to False *OR* set the \"method\" parameter to ReadFromBigQuery.Method.DIRECT_READ.","messagePattern":"The \"use_native_datetime\" parameter cannot be True for EXPORT\\. Please set the \"use_native_datetime\" parameter to False \\*OR\\* set the \"method\" parameter to ReadFromBigQuery\\.Method\\.DIRECT_READ\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery.py","lineNumber":3062,"sourceCode":"      method=None,\n      use_native_datetime=False,\n      output_type=None,\n      timeout=None,\n      *args,\n      query_output_schema=None,\n      **kwargs):\n    self.method = method or ReadFromBigQuery.Method.EXPORT\n    self.use_native_datetime = use_native_datetime\n    self.output_type = output_type\n    self.query_output_schema = query_output_schema\n    self._args = args\n    self._kwargs = kwargs\n    if timeout is not None:\n      self._kwargs['timeout'] = timeout\n\n    if self.method == ReadFromBigQuery.Method.EXPORT \\\n        and self.use_native_datetime is True:\n      raise TypeError(\n          'The \"use_native_datetime\" parameter cannot be True for EXPORT.'\n          ' Please set the \"use_native_datetime\" parameter to False *OR*'\n          ' set the \"method\" parameter to ReadFromBigQuery.Method.DIRECT_READ.')\n\n    if gcs_location and self.method == ReadFromBigQuery.Method.EXPORT:\n      if not isinstance(gcs_location, (str, ValueProvider)):\n        raise TypeError(\n            '%s: gcs_location must be of type string'\n            ' or ValueProvider; got %r instead' %\n            (self.__class__.__name__, type(gcs_location)))\n      if isinstance(gcs_location, str):\n        gcs_location = StaticValueProvider(str, gcs_location)\n\n    if self.output_type == 'BEAM_ROW' and self._kwargs.get('query',\n                                                           None) is not None:\n      if self.query_output_schema is None:\n        raise ValueError(\n            \"Both a query and an output type of 'BEAM_ROW' were specified \"","sourceCodeStart":3044,"sourceCodeEnd":3080,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery.py#L3044-L3080","documentation":"ReadFromBigQuery's EXPORT method writes query/table results to GCS as Avro/JSON files, and the Avro path cannot preserve the native DATETIME logical type. The library raises TypeError at construction time when use_native_datetime=True is combined with method=EXPORT, telling you to either disable native datetime or switch to DIRECT_READ.","triggerScenarios":"Calling ReadFromBigQuery(..., method=ReadFromBigQuery.Method.EXPORT, use_native_datetime=True) in apache_beam/io/gcp/bigquery.py:3062; also leaving use_native_datetime=True (explicitly set) while choosing EXPORT to avoid streaming reads.","commonSituations":"Users migrating to Beam's newer native datetime support keep their existing EXPORT-based pipeline; copy-pasting a DIRECT_READ example but keeping EXPORT; explicitly enabling use_native_datetime for timezone-aware parsing without realizing it only works with the storage API read path.","solutions":["Set use_native_datetime=False in ReadFromBigQuery","Change method=ReadFromBigQuery.Method.DIRECT_READ (requires the BigQuery Storage Read API)","If DATETIME fidelity is not needed, drop the use_native_datetime parameter entirely so it defaults appropriately"],"exampleFix":"// before\nReadFromBigQuery(table='proj:ds.tbl', method=ReadFromBigQuery.Method.EXPORT, use_native_datetime=True)\n// after\nReadFromBigQuery(table='proj:ds.tbl', method=ReadFromBigQuery.Method.DIRECT_READ, use_native_datetime=True)","handlingStrategy":"validation","validationCode":"if method == ReadFromBigQuery.Method.EXPORT and use_native_datetime:\n    raise ValueError('use_native_datetime requires DIRECT_READ')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set use_native_datetime when using DIRECT_READ","Encapsulate ReadFromBigQuery construction in a helper that enforces valid option combos","Review Beam release notes when enabling new type options"],"tags":["python","apache-beam","bigquery","configuration"],"backgroundTag":"conflicting-config-options","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}