django/django · error · GDALException

Invalid data source file "%s"

Error message

Invalid data source file "%s"

What it means

Raised as GDALException by DataSource.__init__ when GDALOpenEx returns a NULL pointer (the open call succeeded at the C level but produced no dataset). The check at datasource.py:84-90 distinguishes this from the caught-exception case: GDAL accepted the call but could not build a dataset, typically because the file is empty or unrecognized after driver probing.

Source

Thrown at django/contrib/gis/gdal/datasource.py:90

                )
            except GDALException:
                # Making the error message more clear rather than something
                # like "Invalid pointer returned from OGROpen".
                raise GDALException('Could not open the datasource at "%s"' % ds_input)
        elif isinstance(ds_input, self.ptr_type) and isinstance(
            ds_driver, Driver.ptr_type
        ):
            ds = ds_input
        else:
            raise GDALException("Invalid data source input type: %s" % type(ds_input))

        if ds:
            self.ptr = ds
            driver = capi.get_dataset_driver(ds)
            self.driver = Driver(driver)
        else:
            # Raise an exception if the returned pointer is NULL
            raise GDALException('Invalid data source file "%s"' % ds_input)

    def __getitem__(self, index):
        "Allows use of the index [] operator to get a layer at the index."
        if isinstance(index, str):
            try:
                layer = capi.get_layer_by_name(self.ptr, force_bytes(index))
            except GDALException:
                raise IndexError("Invalid OGR layer name given: %s." % index)
        elif isinstance(index, int):
            if 0 <= index < self.layer_count:
                layer = capi.get_layer(self._ptr, index)
            else:
                raise IndexError(
                    "Index out of range when accessing layers in a datasource: %s."
                    % index
                )
        else:
            raise TypeError("Invalid index type: %s" % type(index))

View on GitHub (pinned to ae25a40be0)

Solutions

  1. Confirm the file is non-empty and has the correct magic bytes / extension.
  2. Open with ogrinfo <file> outside Django to see the driver-level diagnostic.
  3. Wait for the file to finish writing before opening, or open from a finalized path.

Example fix

// before
ds = DataSource('partial.geojson')  # still being written
// after
# wait for write completion, validate size, then:
ds = DataSource('partial.geojson')
Defensive patterns

Strategy: validation

Validate before calling

import os
def validate_dataset_file(path):
    if os.path.getsize(path) == 0:
        raise ValueError(f'{path} is empty; GDAL returned NULL')
    return path

Type guard

def is_nonempty_file(p):
    return isinstance(p, (str, Path)) and os.path.exists(p) and os.path.getsize(p) > 0

Try / catch

from django.contrib.gis.gdal import GDALException
try:
    ds = DataSource(path)
except GDALException as e:
    if 'Invalid data source file' in str(e):
        log.error('GDAL returned NULL for %s (size=%d)', path, os.path.getsize(path))

Prevention

When it happens

Trigger: DataSource('empty.txt') where no driver claims the file; a zero-byte .geojson; a path to a directory that is not a valid multifile dataset; a file whose header does not match any registered driver.

Common situations: Uploading an empty/truncated file; pointing at a stub file created by touch; GDAL driver not registered for that extension; race condition where the file is still being written.

Related errors

AI-assisted analysis of django/django@ae25a40be0 (2026-08-06). Data as JSON: /api/errors/954732675e8184e6. Report an issue: GitHub.