Atlaslog / Field Notes / Loading & display
Field note · Loading & display
DBF field names truncated at 10 characters and properties read as undefined
Quick answer
DBF from dBase III caps field names at 10 bytes, so population_total exports as population and district_name as district_n. Names that collide overwrite each other, and the frontend reading feature.properties.population_total gets undefined and a NaN legend.
Symptom
- population_total and population_density both become population, and the second overwrites the first.
- feature.properties.population_total is undefined while the legend shows NaN.
- ogrinfo lists 3 fields where the source PostGIS table had 14.
Checklist
- Run ogrinfo -al -so and diff the exported field list against the source table.
- A field count lower than the source means a truncation collision already happened.
- Inspect the DBF field descriptor block: 32-byte entries with an 11-byte name terminated by NUL.
- Print Object.keys(feature.properties) in the browser to learn the real key names.
- Check whether any remaining name is longer than 10 bytes.
Fix
Rename at export time with SQL aliases such as population_total AS pop_tot and population_density AS pop_den, then map the aliases back in the frontend. For long-lived data switch to GeoPackage or GeoJSON, which impose no field-name limit.
Code
ogrinfo -al -so districts.shp | Select-String -Pattern "^[a-z_]+:"
# district_n: String (254.0)
# population: Real (24.15)
# area_sqkm: Real (24.15)
# 少了 population_density# 方案一:导出时用 SQL 重命名
ogr2ogr -f "ESRI Shapefile" out districts.shp -sql "
SELECT district_name AS d_name,
population_total AS pop_tot,
population_density AS pop_den,
area_sqkm AS area_km2,
geom FROM districts"
# 方案二:直接改用 GeoPackage,字段名不受限
ogr2ogr -f "GPKG" districts.gpkg districts.shp
Watch out
- Blaming the frontend parser and re-parsing the DBF: the names were already shortened on disk.
- Keeping two long names that share their first 10 bytes, so one column silently overwrites the other and data is lost.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). DBF field names truncated at 10 characters and properties read as undefined. https://www.jingweizhi.com/en/cookbook/dbf-field-name-limit.html (accessed 2026-11-03).