Analyze spatial data with GeoPandas: troubleshooting guide

GeoPandas makes it practical to analyze vector geospatial data with familiar pandas operations, but spatial workflows fail in distinctive ways. This troubleshooting guide focuses on the problems that most often invalidate results: missing or incorrect coordinate reference systems, measuring in geographic coordinates, mismatched layers in spatial joins, invalid or empty geometries, duplicate rows after joins, and assumptions about planar geometry operations. It provides a repeatable diagnostic workflow, commands for inspecting data, and practical checks before exporting results.

Get Started Browse guides

GeoPandas is useful when your analysis fits comfortably into Python and a GeoDataFrame: read vector data, inspect attributes and geometry, reproject layers, join records by location, calculate distances or areas, overlay boundaries, summarize results, and export a derived dataset. The difficult part is rarely the pandas syntax. It is making sure that the geometry, coordinate reference system, measurement units, and spatial relationship all mean what you think they mean. This guide is for analysts and developers who already have a GeoPandas script but are seeing warnings, empty joins, implausible measurements, missing records, topology errors, or results that change unexpectedly after a transformation. The examples use generic file names so the workflow can be applied to roads, buildings, service requests, parks, waterways, permits, or other location-linked data.

How EDK fits

For: Python developers, GIS analysts, data engineers, researchers, and technical teams working with vector geospatial data in notebooks, scripts, or batch pipelines.

GeoPandas is a focused analysis tool for turning geospatial files and tables into computations about real places. Its core workflow—inspect features, establish their coordinate reference systems, align layers, test spatial relationships, measure geometry, and aggregate results—mirrors the broader problem of making the physical world searchable and computable. The connection to E2 is editorial rather than product equivalence: GeoPandas typically operates on the datasets you explicitly load, while a world-model perspective emphasizes consistent access to many kinds of physical features and the ability to compute across them. A GeoPandas workflow might analyze which roads intersect flood-prone areas, which buildings fall inside a service region, or how many reported issues occur near parks. Those are the same classes of location-aware questions that arise when combining roads, buildings, infrastructure, environmental features, public records, and other geographic data into a common computational view.

•Use GeoPandas-style spatial joins as a clear prototype for questions such as assigning service requests, construction permits, or reported incidents to neighborhoods, road segments, parks, watersheds, or other geographic regions.
•Use CRS-aware measurements and overlays to compare physical features—for example, calculating the area of land-use polygons, finding infrastructure within a distance of roads, or identifying where environmental features overlap administrative boundaries.
•Use the troubleshooting checks in this guide before scaling a workflow from a local GeoDataFrame to a broader geographic computation system that combines many feature types and regions.

Primary object

GeoDataFrame: a pandas-like table with one or more geometry columns.

Core failure area

Incorrect CRS handling, especially confusing set_crs with to_crs.

Common spatial operations

Spatial joins, nearest joins, overlays, clipping, buffering, distance, length, and area.

Measurement warning

Meaningful local distance and area calculations generally require an appropriate projected CRS.

The EDK outcome

Before you start

Python with GeoPandas installed in the environment where the analysis runs.

A vector dataset or spatial table that can be read by GeoPandas, plus any related layer used for a join or overlay.

Basic familiarity with pandas filtering, grouping, and indexing.

The intended spatial question stated precisely, including what counts as a match and what units are required for measurements.

For CRS diagnosis, documentation from the data provider or another reliable source identifying the source coordinate reference system.

Learning objectives

Identify whether a failure comes from missing CRS metadata, a CRS mismatch, invalid geometry, empty geometry, or an incorrect spatial predicate.

Choose correctly between set_crs and to_crs.

Prepare layers for spatial joins, nearest joins, measurements, and overlays.

Validate row counts, match rates, units, geometry types, and duplicate results.

Build a repeatable troubleshooting process before exporting or publishing derived spatial data.

Verification

The source CRS for every layer is known, recorded, and consistent with the source documentation.

CRS alignment occurs before spatial joins, overlays, clipping, or distance predicates.

Measurements are calculated in a projection appropriate for the study area and intended units.

The output row count and duplicate behavior are explained by the chosen spatial relationship.

A sample of known features produces the expected match or non-match result.

Invalid, empty, and missing geometries are counted and handled intentionally.

The final output is opened or plotted independently to confirm that features remain in the expected geographic location.

Troubleshooting

Blank or misplaced map: inspect total_bounds and CRS first. A longitude/latitude layer interpreted as projected coordinates can appear far from the expected location.

CRS mismatch warning: transform one layer with to_crs rather than changing its metadata with set_crs.

Zero distances or implausible areas: verify that the calculation is not being performed in degrees or in a projection unsuitable for the region.

No spatial matches: compare layer bounds, geometry types, CRS, and the predicate. Plot both layers together and test one known feature manually.

Too many output rows: inspect one-to-many matches and aggregate by a stable source identifier if the desired output is one row per feature.

Overlay error about invalid geometries: identify the affected records, inspect them, and decide whether make_valid is appropriate. Do not assume repair preserves the exact topology required by the analysis.

Missing results after filtering: distinguish null geometry from empty geometry and check whether a prior operation dropped or propagated them.

Unexpected geometry types after overlay: inspect keep_geom_type behavior and determine whether lower-dimensional intersections are analytically meaningful.

Different results across environments: record the GeoPandas, Shapely, pyproj, and Python versions, then rerun with the same inputs and explicit CRS definitions.

Next steps

Move stable, repeatable analysis into a tested script or notebook with assertions for CRS, row counts, and expected match rates.

Add a small known-answer test dataset containing points, boundaries, overlaps, empty geometries, and at least one invalid geometry.

Use a spatial database or other indexed processing system when the data volume or repeated-query workload exceeds a comfortable in-memory workflow.

Document source lineage, CRS assumptions, spatial predicates, measurement projections, repair decisions, and export format alongside the output.

For broader physical-world analysis, consider how roads, buildings, infrastructure, environmental features, public records, and other geographic layers can be normalized into a consistent computational workflow.

What you need before debugging

Start with a small reproducible sample and write down the intended spatial question. “Find incidents near roads” is incomplete until you define whether near means intersects, falls within a buffer, or identifies the nearest road. Likewise, “inside a district” may mean within, covered_by, or intersects depending on how boundary-touching features should be treated.

Keep the original input files, the Python environment, and a representative sample available. GeoPandas relies on related geospatial libraries for projections and geometry operations, so differences between environments can affect warnings, supported predicates, or output geometry types.

•Confirm that the expected geometry column is active.
•Check whether the CRS is present and whether related layers use compatible CRSs.
•Inspect geometry types, null geometries, empty geometries, and invalid geometries.
•Print bounds and row counts before and after each spatial operation.
•Separate data problems from logic problems by plotting or exporting a small sample.

Step 1: inspect the GeoDataFrame before changing anything

Many apparent GeoPandas bugs are data-contract problems. A file can load successfully while containing no CRS, an unexpected active geometry column, null geometries, or coordinates outside the intended region. GeoPandas documents CRS as metadata that explains how coordinates relate to locations on Earth; without it, coordinate transformations cannot be performed reliably and exported files may be misinterpreted. (docs.geopandas.org)

Run an inspection pass before filtering, joining, buffering, or measuring:

•Use gdf.shape and gdf.columns to verify row and field counts.
•Use gdf.geometry.name to confirm the active geometry column.
•Use gdf.geom_type.value_counts(dropna=False) to identify mixed or unexpected geometry types.
•Use gdf.geometry.isna().sum() and gdf.geometry.is_empty.sum() to detect missing and empty geometries.
•Use gdf.geometry.is_valid.value_counts(dropna=False) to identify invalid shapes.
•Use gdf.crs and gdf.total_bounds to check the coordinate system and geographic extent.

Step 2: fix CRS mistakes without moving data accidentally

The most consequential CRS mistake is confusing metadata assignment with coordinate transformation. set_crs tells GeoPandas how to interpret existing coordinate values; it does not move the coordinates. to_crs transforms coordinates into another CRS. Overriding a known CRS can place features in the wrong location even though the code runs. (geopandas.org)

If a dataset was created from longitude and latitude columns and has no CRS, assign a CRS only after verifying the source coordinate convention. If a layer already has a known CRS, transform it rather than replacing its metadata.

•Use points.set_crs('EPSG:4326') to label coordinates that are already longitude and latitude in WGS 84.
•Use points.to_crs(polygons.crs) to transform points into the polygon layer's CRS before a spatial join.
•For local distance, area, or buffer operations, use a suitable projected CRS rather than EPSG:4326.
•GeoPandas provides estimate_utm_crs() to estimate a UTM CRS from dataset bounds, but inspect the result and confirm that one UTM zone is suitable for the study area.
•Record the source CRS and the analysis CRS separately so later users can distinguish original data from transformed data.

Step 3: diagnose spatial joins and unexpected row counts

A spatial join is not an ordinary key-based merge. GeoPandas combines records according to a spatial relationship between geometries. A point can match several polygons, and a polygon can match many points, so the output may contain more rows than the left-hand input. GeoPandas supports predicate-based joins through sjoin() and proximity-based joins through sjoin_nearest(). (geopandas.org)

Align CRSs before joining, make the predicate explicit, and inspect the match structure rather than assuming that every input feature produces exactly one output row.

•Use predicate='within' when points must fall inside polygons.
•Use predicate='intersects' when any geometric overlap should count.
•Use predicate='contains' when the left-hand geometry should contain the right-hand geometry.
•Use sjoin_nearest only when nearest-feature semantics are intended; consider max_distance and inspect the distance column.
•After joining, inspect index_right, unmatched rows, duplicate source identifiers, and the number of matches per source feature.
•Aggregate explicitly when the desired output is one row per road, building, request, permit, or other source entity.

Step 4: troubleshoot measurements, overlays, and geometry failures

If an area is a very small number or a distance looks like a fraction of a degree, the data may still be in a geographic CRS. Longitude and latitude are angular coordinates, not a uniform local measurement system. Reproject to an appropriate projected CRS before using area, length, buffers, or distance-based predicates.

Overlay operations can also fail or produce fewer geometries than expected. GeoPandas overlay supports intersection, union, identity, symmetric difference, and difference. Its documentation states that make_valid=True attempts to correct invalid input geometries, while make_valid=False raises an error for invalid inputs. Overlay operations are planar and do not account for a third coordinate dimension. (geopandas.org)

•Count invalid geometries before an overlay and retain identifiers for affected records.
•Repair only when appropriate, then compare counts, geometry types, and boundaries before and after repair.
•Use keep_geom_type consciously; restricting output to the input geometry type can discard lower-dimensional intersections.
•Treat missing and empty geometries differently. GeoPandas documents that missing geometries generally propagate as missing values, while empty geometries are real geometry objects whose results depend on the operation. (geopandas.org)
•For broad or global measurements, assess whether one projected CRS is appropriate for the full study area. A local projection may not be suitable for a large geographic extent.

Step 5: validate the result before exporting

A script that completes without raising an exception has not necessarily produced a correct spatial result. Add assertions and checkpoints around every operation that can change feature counts, geometry types, CRS, or units.

Validation should combine automated checks with a small visual or known-answer review. For example, choose several features whose expected region, road, park, or boundary relationship is already known. Check those records directly instead of relying only on aggregate totals.

•Compare input and output row counts and explain every increase or decrease.
•Calculate the unmatched rate for left joins and investigate unexpected null matches.
•Check duplicate counts for the identifier that should remain unique.
•Confirm that output bounds remain in the expected geographic area.
•Inspect geometry types after overlay or repair.
•Plot a small sample of both source and result layers together.
•Open the exported file in an independent GIS viewer or reload it in a fresh Python process.
•Store CRS assumptions, predicates, measurement units, and repair decisions with the output metadata.

Workflow

1. Create a minimal diagnostic script

Keep the failing input and reduce the operation to a small sample. Print the row count, columns, active geometry name, CRS, bounds, geometry types, null geometries, empty geometries, and invalid geometries before applying filters or joins.

import geopandas as gpd

left = gpd.read_file("left.gpkg")
right = gpd.read_file("right.gpkg")

for name, gdf in {"left": left, "right": right}.items():
    print(name, "rows:", len(gdf))
    print(name, "geometry:", gdf.geometry.name)
    print(name, "crs:", gdf.crs)
    print(name, "bounds:", gdf.total_bounds)
    print(name, "types:\n", gdf.geom_type.value_counts(dropna=False))
    print(name, "missing:", gdf.geometry.isna().sum())
    print(name, "empty:", gdf.geometry.is_empty.sum())
    print(name, "invalid:", (~gdf.geometry.is_valid).sum())

2. Confirm the source CRS

Use the data provider's documentation, file metadata, or a known coordinate convention to establish the source CRS. Do not infer a CRS only from the size of coordinate values if a reliable source is available.

print(points.crs)
print(regions.crs)

# Only when the coordinates are known to be WGS 84 longitude/latitude:
if points.crs is None:
    points = points.set_crs("EPSG:4326")

3. Assign or transform the CRS deliberately

If coordinates have no CRS but their meaning is known, assign the correct CRS with set_crs. If coordinates need to be transformed, use to_crs. Never use set_crs as a substitute for reprojection.

points_for_join = points.to_crs(regions.crs)

# Use a projected CRS for local measurements.
measurement_crs = points.estimate_utm_crs()
points_metric = points.to_crs(measurement_crs)

4. Run the spatial operation with an explicit relationship

Choose the predicate that matches the question and inspect the resulting match columns. For a point-in-polygon operation, within is often appropriate; for general overlap, intersects may be more suitable.

joined = gpd.sjoin(
    points_for_join,
    regions,
    how="left",
    predicate="within"
)

print("input points:", len(points_for_join))
print("joined rows:", len(joined))
print("unmatched points:", joined["index_right"].isna().sum())
print("duplicate point indexes:", joined.index.duplicated().sum())

5. Validate measurements and geometry output

Check that units are appropriate, geometry types are expected, and counts are plausible. For overlays, inspect invalid inputs and compare the output before and after any repair. For joins, aggregate explicitly when the analytical result should have one row per source feature.

regions_metric = regions.to_crs(regions.estimate_utm_crs())
regions_metric["area_m2"] = regions_metric.geometry.area

summary = (
    joined.groupby("region_id", dropna=False)
          .size()
          .rename("feature_count")
          .reset_index()
)

print(summary.head())

6. Export only after independent verification

Check known features, output bounds, duplicate behavior, CRS metadata, and measurement units. Reload the exported file or open it in an independent GIS application to confirm that the result remains in the expected location.

assert joined.crs == points_for_join.crs
assert joined.geometry.notna().all()

joined.to_file("validated_output.gpkg", layer="results", driver="GPKG")
reloaded = gpd.read_file("validated_output.gpkg", layer="results")
print(reloaded.crs)
print(reloaded.total_bounds)
print(reloaded.head())

Questions teams ask

Why does my spatial join return no matches?

First compare left.crs and right.crs. If one layer is in longitude and latitude and the other is projected, transform one layer with to_crs() before joining. Then inspect total_bounds, geometry types, and a plotted sample. Finally confirm that the predicate matches the question: within, contains, intersects, and nearest do not mean the same thing.

Should I use set_crs or to_crs?

Use set_crs when the coordinate values already represent a known CRS but the metadata is missing or incorrect. Use to_crs when the geometry needs to be transformed into another CRS. set_crs does not transform coordinates; to_crs does. (geopandas.org)

Why are my area and distance values wrong?

You may be measuring in a geographic CRS such as EPSG:4326, where coordinates are expressed in degrees. Reproject to an appropriate projected CRS for the region and calculation, then compute area, length, distance, or buffers. For large or global extents, evaluate whether one projection can represent the intended measurement accurately.

Why did a spatial join create duplicate rows?

The spatial relationship may be one-to-many: one point can intersect several polygons, or one polygon can contain many points. Inspect the right-hand match identifier and decide whether you need every match, the nearest match, or an aggregation such as counts by region. GeoPandas documents spatial joins as relationship-based combinations rather than ordinary key joins. (geopandas.org)

What should I do when overlay reports invalid geometries?

Count invalid geometries, inspect representative features, and determine whether repairing them is acceptable for your analysis. GeoPandas overlay can call make_valid by default, while make_valid=False raises an error for invalid inputs. Compare geometry counts, types, and boundaries after repair before using the result. (geopandas.org)

How are empty geometries different from missing geometries?

A missing geometry represents an unknown or absent value, while an empty geometry is a real geometry object with no coordinates. GeoPandas treats them differently: missing values commonly propagate through operations, while empty geometries participate according to the operation's rules. Check isna() and is_empty separately. (geopandas.org)

Keep exploring