🐞 Issue: API.mutate(create/update/delete) succeeds in DynamoDB but throws GraphQL error when using belongsTo LazyReference (Room → Space)

[bokute2010]

Describe the bug

When creating a model with a belongsTo relationship using Amplify Gen2 + API.mutate (GraphQL/AppSync), the item is successfully written to DynamoDB, but the mutation throws a GraphQL error during response resolution.

This happens when the generated Swift model constructor accepts a related object (Space) via LazyReference, but no explicit foreign key (spaceId) exists in the schema.

This behavior is confusing because:

The code is generated by Amplify

The mutation appears to fail

But the data is actually persisted

Steps To Reproduce

1. Create schema (Backend Amplify Gen2)

Room: a.model({
  name: a.string().required(),
  owner: a.string(),
  spaceId: a.id().required(),
  space: a.belongsTo('Space', 'spaceId'),
})

Space: a.model({
  name: a.string().required(),
  owner: a.string(),
})

2. Generated Swift Model (excerpt)

public struct Room: Model {
  public let id: String
  public var name: String
  internal var _space: LazyReference<Space>

  public var space: Space? {
    get async throws {
      try await _space.get()
    }
  }

  public init(
    id: String = UUID().uuidString,
    name: String,
    owner: String? = nil,
    space: Space? = nil
  ) {
    self.id = id
    self.name = name
    self.owner = owner
    self._space = LazyReference(space)
  }
}

3. Create a Space using API.mutate(.create)
- Create a Room and pass the Space object into the generated initializer:
let room = Room(
  name: "Living Room",
  owner: owner,
  space: space   // passed as LazyReference
)

try await Amplify.API.mutate(
  request: .create(room)
)

Expected behavior

One of the following would be expected:

The generated Swift model should not expose an initializer that accepts a related object when using API-only GraphQL mutations
OR

The documentation should clearly state that:

Passing related objects only works with DataStore

For API.mutate, foreign keys must be set explicitly
OR

Amplify Gen2 should automatically map LazyReference → foreign key (spaceId) when performing create mutations

Amplify Framework Version

2.53.2

Amplify Categories

DataStore, API

Dependency manager

Swift PM

Swift version

6

CLI version

14.2.3

Xcode version

Version 16.2

Relevant log output

<details>
<summary>Log Messages</summary>


INSERT LOG MESSAGES HERE

</details>

Is this a regression?

Yes

Regression additional context

Root Cause Analysis (Suspected)

LazyReference does not serialize into the GraphQL CreateRoomInput

No spaceId is written to DynamoDB

During response resolution, AppSync attempts to resolve:

createRoom {
    space {
      id
    }
}

Since spaceId is null, resolver returns null

GraphQL throws because Space.id is non-nullable

This results in a successful write + failed response.

Platforms

No response

OS Version

ios 18.6.2 (ipad), 18.7.3 (iphone XR), 18.2 (Simulator)

Device

iphone XR, Ipad (9th generation), Simulator iphone 16 pro

Specific to simulators

No response

Additional context

No response

[ekjotmultani]

Thank you for raising this issue, we will investigate and get back to you

[bokute2010]

How's it going, team ?

[jvh-aws]

Thanks for the follow up and creating the issue @bokute2010! I can locally reproduce your findings and receive the same error that you report.

However, to make the schema compile and deploy, I had to add a hasMany relation to the space, i.e.

const schema = a.schema({
  Space: a
    .model({
      rooms: a.hasMany('Room', 'spaceId'),
    })
})

It seems to me like the response from AppSync does not include the nested object (space), when we are creating the room.

Could you please confirm if you are using any authorization rules for your schemas and potentially share what they are (e.g. allow.owner())?

It could be, that the issue you are experiencing is related to the behavior in Amplify CLI Gen2, discussed here. Handling of the specific behavior is also discussed here for amplify-flutter.

As a workaround, you could try to catch the error and add specific handling for partial responses, which ignores the parsing error. We will continue investigating this and potential remediation on our side.

Example Code:

let result = try await Amplify.API.mutate(request: .create(newRoom))

switch result {
case .success(let createdRoom):
    // ...
case .failure(let graphQLError):
    switch graphQLError {
    case .error(let errors):
        // Handle error
    case .partial(let data, let errors):
        // Assume creation was successful but result couldn't be read
        // Potentially check errors[0].message to ensure it was a failure to get the nested object

[bokute2010]

Thanks for looking into this and confirming reproduction.

Yes, I am using authorization rules on the models. For example:

Room:

• allow.owner()

Space:

• allow.owner()

Both models are owned by the same authenticated user, and the Room is created with the same owner value as the Space.

Even with this setup, the Room is successfully written to DynamoDB, but the mutation fails during response parsing when resolving the nested Space object.

This matches your observation that the AppSync response does not include the nested object during create, or potentially fails authorization during nested resolution.

In my case, adding an explicit spaceId field resolves part of the issue, but the generated Swift model still exposes an initializer that accepts a related object, which is misleading when using API.mutate.

I agree that handling partial responses is a possible workaround, but from a DX perspective it would be helpful if:

• The Swift codegen avoided suggesting object-based initializers for API-only usage, or
• The documentation explicitly differentiated DataStore vs API.mutate behavior for relationships.

[jvh-aws]

@bokute2010 Thanks for providing further details! We will continue investigating and get back to you.