Nested Object POST Request Uninformative Error Messages

[WillJeynes]

API Platform version(s) affected: 3.0.10

Description
When trying to create an object with a one to many relationship by nesting child objects in an array getting error message 'Nested documents for attribute "attributes" are not allowed. Use IRIs instead.'. The cause of this error is not having a remove attributes function, which is never called and this actual problem is not hinted at in the error.

How to reproduce
Make a one to many relationship in doctrine and remove the removeWhatever function in the parent class. Set up a group for a post request. Try to add an element.

[soyuka]

Hi @WillJeynes — after triage, the error "Nested documents for attribute X are not allowed. Use IRIs instead." is working as intended. It signals the framework cannot populate the nested collection through its declared accessors.

There are two supported ways to handle nested children in API Platform:

1. IRI references — send "attributes": ["/attributes/1", "/attributes/2"] in the payload. This is the default and what the message points to.

2. Inline nested writes (embedding) — to accept full nested objects, the framework requires both:

   • Matching denormalization groups on the related resource (#[Groups([...])] on Attribute properties), and
   • For to-many relations, adder/remover methods on the parent (addAttribute(Attribute $a) / removeAttribute(Attribute $a)). The Symfony Serializer uses these to mutate the collection; a setAttributes(Collection) alone is not enough.

   See https://api-platform.com/docs/core/serialization/#embedding-relations for the embedding pattern and https://symfony.com/doc/current/components/serializer.html#handling-nested-objects for the adder/remover convention.

If the adder/remover methods are missing on the parent class, the serializer reaches the "nested documents not allowed" path because it has no way to write into the collection. The pre-existing message points at the IRI workaround; the alternative is to add the adder/remover (and groups) so embedding works.

Closing as documented behavior — happy to reopen if the above doesn't cover your case.