django/django · error · TypeError

ForeignKey mapping must be of dictionary type.

Error message

ForeignKey mapping must be of dictionary type.

What it means

TypeError raised when a ForeignKey model field's mapping value is not a dict. LayerMapping requires ForeignKey mappings to be dictionaries mapping related-model field names to OGR column names so it can look up the related object.

Source

Thrown at django/contrib/gis/utils/layermapping.py:288

                self.geom_field = field_name
                self.coord_dim = coord_dim
                fields_val = model_field
            elif isinstance(model_field, models.ForeignKey):
                if isinstance(ogr_name, dict):
                    # Is every given related model mapping field in the Layer?
                    rel_model = model_field.remote_field.model
                    for rel_name, ogr_field in ogr_name.items():
                        idx = check_ogr_fld(ogr_field)
                        try:
                            rel_model._meta.get_field(rel_name)
                        except FieldDoesNotExist:
                            raise LayerMapError(
                                'ForeignKey mapping field "%s" not in %s fields.'
                                % (rel_name, rel_model.__class__.__name__)
                            )
                    fields_val = rel_model
                else:
                    raise TypeError("ForeignKey mapping must be of dictionary type.")
            else:
                # Is the model field type supported by LayerMapping?
                if model_field.__class__ not in self.FIELD_TYPES:
                    raise LayerMapError(
                        'Django field type "%s" has no OGR mapping (yet).' % fld_name
                    )

                # Is the OGR field in the Layer?
                idx = check_ogr_fld(ogr_name)
                ogr_field = ogr_field_types[idx]

                # Can the OGR field type be mapped to the Django field type?
                if not issubclass(ogr_field, self.FIELD_TYPES[model_field.__class__]):
                    raise LayerMapError(
                        'OGR field "%s" (of type %s) cannot be mapped to Django %s.'
                        % (ogr_field, ogr_field.__name__, fld_name)
                    )
                fields_val = model_field

View on GitHub (pinned to ae25a40be0)

Solutions

1. Provide the FK mapping as a dict: {related_field_name: ogr_column_name}.
2. Confirm the model field is actually a ForeignKey (so the dict form is expected).
3. If you intended a plain field reference, change the model field to a non-FK type.

Example fix

# before
mapping = {'city': 'CITY_NAME'}  # TypeError

# after
mapping = {'city': {'name': 'CITY_NAME'}}

from django.db import models

def validate_fk_mapping_shape(model, mapping):
    for k, v in mapping.items():
        try:
            f = model._meta.get_field(k)
        except Exception:
            continue
        if isinstance(f, models.ForeignKey) and not isinstance(v, dict):
            return f'{k} FK mapping must be a dict'
    return None

from django.db import models

def fk_mappings_are_dicts(model, mapping):
    for k, v in mapping.items():
        try:
            f = model._meta.get_field(k)
        except Exception:
            continue
        if isinstance(f, models.ForeignKey) and not isinstance(v, dict):
            return False
    return True

try:
    LayerMapping(Model, path, mapping)
except TypeError as e:
    if 'must be of dictionary type' in str(e):
        # wrap the value in a dict {rel_field: ogr_col}
        ...

When it happens

Trigger: Passing mapping = {'city': 'CITY_NAME'} (string) for a ForeignKey instead of {'city': {'name': 'CITY_NAME'}}; passing a list or a single OGR column name where the FK dict is required.

Common situations: Misreading the LayerMapping docs; assuming FK mapping uses the same string form as scalar fields; auto-generating mappings from introspection that skip FK handling.

Related errors

• ForeignKey mapping field "%s" not in %s fields.
• Unique keyword argument must be set with a tuple, list, or s
• Invalid initialization input for LineStrings.
• Too many dimensions.
• Each coordinate should be a sequence (list or tuple)

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