Skip to main content

Troubleshooting Asset Migrations and Backfill

Summary​

This page covers migration and backfill symptoms. There is one authored migration; in development the service auto-migrates. A model mismatch at startup indicates a pending migration. Backfill is a console-mode ETL that preserves CompatId. A missing CompatId or a backfill conflict points to identity mapping. Production migration and backfill ownership is unconfirmed. This page never includes commands; it is observational only.

Audience​

Support engineers, developers, and DevOps engineers investigating a startup model mismatch, a backfill conflict, or a missing CompatId after data movement.

Symptoms​

  • The service reports a model mismatch at startup.
  • A backfill run reports a conflict.
  • An asset is missing its CompatId.
  • Data movement outcomes differ between environments.

Cause​

Scope​

This page covers the pending-migration startup signal and backfill identity mapping via CompatId. It does not include commands and does not cover production ownership, which is unconfirmed.

Likely causes​

  • A pending migration has not been applied, so the model mismatch appears at startup.
  • The backfill encountered an identity-mapping conflict, because CompatId preservation is central to the ETL.
  • An asset is missing a CompatId, which points to an identity-mapping gap.
  • The environment differs in whether auto-migration applied, since development auto-migrates.

Resolution​

Safe diagnostics​

  • Treat a startup model mismatch as a pending-migration signal and confirm the migration state with the owning team; do not run migration commands from this page.
  • Correlate a backfill conflict with CompatId identity mapping, since the ETL preserves CompatId.
  • Confirm whether the affected asset has a CompatId; a missing one indicates an identity-mapping gap.
  • Confirm the environment's auto-migration behavior, since development auto-migrates while production ownership is unconfirmed.

Validation​

  • Confirm the model mismatch clears once the pending migration is applied by the owning team.
  • Confirm backfilled assets carry the expected CompatId.
  • Confirm the CompatId unique index is consistent, since it is the only database unique index in the model.

Evidence to Collect​

  • The startup mismatch message, without credentials or connection details.
  • The backfill conflict indication and the affected asset.
  • Whether a CompatId is present.
  • A correlation identifier and timestamp.

Escalation​

Route migration application and schema questions to the database owner. Route backfill identity mapping and CompatId behavior to the asset or backend team. Production migration and backfill ownership is Requires confirmation.

Source References​

  • microservices/src/asset-service/Infrastructure/Persistence.cs
  • microservices/src/asset-service/Infrastructure/AssetDbContext.cs
  • microservices/scripts/smoke-asset.ps1

See Also​

Keywords​

migration, backfill, compatid, identity mapping, startup mismatch

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-17
  • Review cycle: Quarterly