Shopware 6 validates entity payloads before writing, and rejects values that do not match the expected type, format or a foreign-key reference. Common causes are UUIDs without the expected 32-character hex format, dates in the wrong shape, enum-like fields given an unexpected value, and references to records that do not exist. The bigger practical problem is the Sync API: when you send many entities in one request and one fails, the response does not reliably tell you which one, so a batch of 500 products fails as a unit and you are left bisecting.
What Shopware is checking
Shopware 6 validates entity payloads against its data abstraction layer definition before writing anything. The message appears when a value does not satisfy that definition: wrong type, wrong format, a value outside an accepted set, or a reference to a record that does not exist.
The message is a template completed at runtime with the field and the expected type. Whether you see that detail depends entirely on whether your error handling kept the full payload.
The recurring causes
ID format. Shopware expects 32-character lowercase hex, no hyphens. A canonical UUID with hyphens is 36 characters and is rejected. So is uppercase hex. This is the most common single cause when a system generates IDs elsewhere and passes them in.
Dates. Wrong format, missing timezone, or a value the field’s type does not accept.
Enum-like fields. Values validated against a defined set. A plausible value that is not in the set is invalid.
Foreign keys to records that do not exist. A product referencing a tax ID, currency or sales channel that is absent. This one presents as a validation error rather than as a missing-record error, which sends people looking at formats when the problem is ordering: the referenced record has not been created yet.
Missing required fields. Especially when building payloads by hand rather than from a full example.
The Sync API problem
This is the part that turns a small error into a long afternoon.
The Sync API lets you send many operations in one request, which is exactly what you want for bulk import. But when one operation is rejected, the response does not reliably identify which one. You get a validation failure for a request containing 500 products and no indication of which product caused it.
The remaining options are all unattractive: bisect the batch, shrink batches until failures are cheap to locate, or validate everything client-side before sending.
In practice, use smaller batches than feels efficient. The throughput you lose is far less than the time you lose bisecting a failed batch of 500, and the difference gets worse as your catalogue grows.
Debugging approach
Log the complete error payload. It usually contains a JSON pointer to the offending field. Everything else here is a fallback for when that has been discarded.
Fetch an existing working record via the API and compare shapes. This reveals fields the admin UI fills in that your client does not.
Check ID formatting first if IDs cross a system boundary.
Check referenced records exist before assuming a format problem. Ordering issues are common in imports.
Reduce the batch if using Sync, until the failure is attributable.
What we do differently
Payloads are validated before they are sent. A malformed ID or a missing required field is caught locally, where the error names the record, instead of remotely, where it names nothing.
A batch is not the unit of success. Records are written in small batches with per-record error handling, so one bad record is isolated and reported rather than taking 499 good ones with it.
Referential ordering is explicit. Dependencies are created before the records referencing them, rather than relying on the order a source system happened to return.
Rejected records go to a dead-letter queue with their full payload and response, so a person can see exactly what was sent and what came back without reconstructing it from logs.
We diff the Shopware API definition as it changes, so a tightened validation rule or a new required field is planned work rather than a failed import discovered the next morning.
Frequently asked questions
Why is the message cut off?
Because it is a template completed at runtime with the field and expected type, and error handling frequently keeps only the first part. Log the full error payload from the Admin API: it contains a pointer to the offending field, usually as a JSON pointer path into the payload you sent. Losing that detail is self-inflicted and it is the single most common reason this error is hard to diagnose.
Our UUIDs look fine but get rejected.
Shopware expects IDs as 32-character lowercase hex without hyphens. A canonical UUID with hyphens is 36 characters and will be rejected, as will uppercase hex. If you generate IDs in another system and pass them through, normalise the format at the boundary rather than assuming both sides agree on what a UUID looks like.
The Sync API does not tell us which entity failed.
That is a known and long-standing complaint. When a sync request carries many operations and one is rejected, the response often does not identify which. The practical mitigations are smaller batches, deterministic ordering so the position is meaningful, and validating payloads before sending. It is also a good argument for per-record error handling rather than batch-or-nothing writes.
It fails in a headless sales channel but not in the admin.
The admin interface fills in defaults and derived values that an API client does not. A payload assembled by hand is missing fields the admin would have supplied silently. Compare against what the API returns for an existing, working record: that shows you the complete shape rather than the minimum you guessed at.
How do you avoid batch failures blocking everything?
By not making a batch the unit of success. Records are validated before sending, batches are kept small enough that a failure is cheap, and any record that is rejected is isolated and reported rather than taking its batch with it. Writes are idempotent so replaying the remainder is safe.
// scoping request
Seeing this in production and want it to stop being your problem? We design, build, and permanently operate the pipeline, including the validation and retry logic that stops this class of failure reaching you. Fixed-price scoping quote within 48 hours.