Import Drupal Configuration Before Creating Content Entities
A deployment can fail even when its field names and bundles look identical. Drupal configuration entities carry UUIDs, and creating content types or Paragraph types independently in each environment produces different identities.
The symptom
drush config:import reports that content or Paragraph entities must be deleted before configuration can be imported. The import plan may appear to create and delete similarly named configuration.
The cause
A migration script created configuration entities and content before the canonical exported configuration was imported. Drupal correctly refused to replace bundles that already contained content.
The safe sequence
- Back up the database.
- Deploy module and theme code.
- Import
config/sync. - Run idempotent content migrations.
- Rebuild caches and verify routes.
Prevention
Store field storage, field instances, form displays, content types, and Paragraph types in configuration. Store editorial copy and entity revisions in the database. Test the exact sequence on stage before production.
Why identical machine names are not enough
Two configuration entities can have the same human label and machine name while still representing different configuration identities. When a bundle is independently created in two environments, its UUID can differ from the UUID in the canonical configuration export. Drupal then sees the import as replacement rather than confirmation that the same configuration already exists.
If content has already been created against that independently generated bundle, replacing it becomes unsafe. Drupal's refusal to import is protecting the relationship between stored content and its configuration.
Make content migrations depend on configuration
An idempotent content migration should assume the bundle and fields already exist. It can then create or update editorial entities without taking responsibility for defining the application schema. This gives configuration import and content migration separate, understandable ownership.
When the migration is run again, use stable identifiers or another deterministic lookup so it updates the intended content instead of creating duplicates.
Recover by restoring the canonical order
If the wrong order has already been used in a non-production environment, back up the database, remove disposable content created against the conflicting configuration, import the canonical configuration, and rerun the content migration. On production, investigate the affected entities carefully before deleting anything. The presence of real editorial content changes the recovery problem.
Key Takeaways
- Configuration identity matters in addition to machine names.
- Import structural configuration before creating content that depends on it.
- Keep content migrations idempotent and separate from schema creation.