Convert GeoJSON with GDAL: troubleshooting guide

What GDAL is converting—and why the distinction matters

GDAL’s vector utilities operate through OGR drivers. The GeoJSON driver reads and writes GeoJSON and presents it as a datasource containing one OGR layer. A GeoJSON source may be a local `.geojson` or `.json` file, a URL, or text passed directly to the driver. A top-level `FeatureCollection` becomes a layer containing its features; a top-level GeoJSON geometry or feature is treated as a one-feature layer. (gdal.org)

The conversion command is usually shaped like `ogr2ogr <destination> <source> [<layer>]`. The destination format can be inferred from the filename in many cases, but specifying it with `-f` makes scripts easier to read and less dependent on filename conventions. `ogr2ogr` also supports coordinate-system assignment and transformation, field selection, spatial and attribute filtering, geometry-type controls, layer naming, and creation options. (gdal.org)

• •Inspection answers: Can GDAL open the input? What is the layer called? What geometry types and fields are present? Is a CRS reported? What are the extent and feature count?
• •Conversion answers: Which output driver is being used? Are coordinates transformed? Are fields selected or remapped? Are layer creation options changing the representation?
• •Validation answers: Does the output reopen? Does it have the expected spatial extent, geometry, field schema, and coordinate interpretation?

Prerequisites and a controlled diagnostic setup

Install a GDAL distribution that includes the command-line utilities `ogrinfo` and `ogr2ogr`. Confirm the executable and version before debugging. Version differences matter because current GDAL documentation includes options and behaviors added in particular releases, including newer driver-selection and output features.

Keep a small copy of the source if the original is large or remote. Do not begin by converting the entire dataset. First establish a reproducible working directory and record the exact input path, GDAL version, source URL if applicable, intended output format, and intended CRS.

• •`ogrinfo --version`
• •`ogr2ogr --version`
• •`ogrinfo --formats | grep -i geojson` on Unix-like systems, or use `ogrinfo --formats` and search for GeoJSON on Windows
• •`ogr2ogr --help` to confirm the options available in the installed version.

Step 1: inspect the GeoJSON before converting it

Start with read-only inspection. The `-ro` flag prevents update mode, while `-al -so` requests a summary across layers without dumping every feature. This is safer for large files than immediately listing all features. `ogrinfo` reports information such as the layer, projection, schema, feature count, and extent. (gdal.org)

For a local file, run:

• •`ogrinfo -ro -al -so input.geojson`
• •`ogrinfo -ro -al -so -json input.geojson`
• •`ogrinfo -ro input.geojson OGRGeoJSON -limit 3 -geom SUMMARY` if the layer is reported as `OGRGeoJSON`.
• •If the filename is ambiguous or automatic detection fails on a URL or unusual file, try `ogrinfo -ro -if GeoJSON input.data` on GDAL versions that support the `-if` option. The GeoJSON driver documentation also describes the `GeoJSON:` prefix as a way to remove ambiguity. (gdal.org)
• •Look for these specific conditions: an absent CRS, an unexpected extent, a geometry type that is mixed or unknown, fields that vary across features, a top-level object that is not a `FeatureCollection`, or an input that is actually an HTML error page returned by a URL. A file extension alone does not prove that the contents are valid GeoJSON.

Step 2: run the smallest useful conversion

Once the source opens, convert it to a format that is easy to inspect. GeoPackage is often a useful diagnostic target because it stores a named layer in a single SQLite-based file and avoids some of the field-name and type limitations associated with older interchange formats. The command below creates a GeoPackage layer named `features`:

• •`ogr2ogr -f GPKG output.gpkg input.geojson -nln features`
• •`ogr2ogr -f GPKG output_sample.gpkg input.geojson -nln features -limit 100` if the installed version and driver support the intended bounded test workflow.
• •`ogr2ogr -f GPKG output.gpkg input.geojson -nln features -select id,name,status` to restrict attributes when those fields exist.
• •After conversion, inspect the destination rather than trusting the command’s completion message:
• •`ogrinfo -ro -al -so output.gpkg`
• •`ogrinfo -ro output.gpkg features -limit 3 -geom SUMMARY`.
• •If the destination opens and its extent, count, geometry, fields, and CRS match expectations, repeat the conversion without the sample limitation. Keep the successful command in a script or documented run log so the operation can be reproduced.

Step 3: make GeoJSON CRS and RFC 7946 behavior explicit

GeoJSON conversions frequently fail at the boundary between legacy GeoJSON behavior and RFC 7946 behavior. The GDAL GeoJSON driver can write RFC 7946 output with the layer creation option `RFC7946=YES`. In that mode, coordinates are geographic over the WGS 84 ellipsoid, and GDAL reprojects from another layer CRS when necessary. The output may also use RFC 7946 polygon orientation, antimeridian handling, and a default of seven decimal places. (gdal.org)

To create RFC 7946 GeoJSON from a source whose CRS is already correctly identified, use:

• •`ogr2ogr -f GeoJSON output.json input.gpkg -lco RFC7946=YES`
• •`ogr2ogr -f GeoJSON output.json input.gpkg source_layer -t_srs EPSG:4326 -lco RFC7946=YES`.
• •If the input lacks a CRS but you know what the coordinates represent, assign it with `-a_srs`, then transform if needed:
• •`ogr2ogr -f GeoJSON output.json input.geojson -a_srs EPSG:3857 -t_srs EPSG:4326 -lco RFC7946=YES`.
• •Do not copy that CRS command without confirming the source. EPSG:3857 is only an example. If the actual coordinates are longitude and latitude, assigning EPSG:3857 would make the data wrong. When the source CRS is genuinely unavailable, the correct response is to identify it from authoritative metadata or report that reprojection cannot be performed safely.

Step 4: validate geometry, attributes, and output semantics

A conversion can complete while producing a result that is unsuitable for the next system. Validate at least the feature count, extent, geometry type, CRS, field names, null behavior, and a few representative geometries. Compare a known coordinate or bounding box from the source with the destination.

The GeoJSON driver supports heterogeneous geometry layers by default. It can preserve different geometry types in one layer, while `GEOMETRY_AS_COLLECTION=YES` can wrap geometries as collections when a homogeneous representation is required. The driver also derives a union of feature properties when features do not share identical property schemas. Those behaviors can be useful, but they may surprise consumers that expect one geometry type or a stable field definition. (gdal.org)

• •Reopen the output with `ogrinfo`; do not validate only by opening it in a web map.
• •Check that longitude and latitude are in the expected order for GeoJSON output.
• •Test a polygon near a boundary or antimeridian if those cases matter to your data.
• •Compare a few source and destination feature properties, especially arrays, dates, long strings, and nullable fields.
• •Record the source CRS, target CRS, GDAL version, command, and output creation options with the converted dataset.