skip to content

In SwiftData, why can't a @ModelActor hand a model object to the main actor, and how does PersistentIdentifier let the two sides share it?

level: seniorimportance: should knowfreq 48%

answer

  1. models are not Sendable
  2. a Sendable stand-in
  3. permanent only after a save
  4. each side loads its own copy
  5. registered vs fetched on demand

basics

~20 s

@Model classes are deliberately not Sendable, and each belongs to one ModelContext, so Swift 6 rejects returning one across actors. Pass its persistentModelID, a Sendable, Codable PersistentIdentifier, after saving, and load the model again in the receiving context.

solid answer

~40 s

The `@Model` macro generates an **unavailable** `Sendable` conformance whose message says to use a `ModelActor` or the model's `persistentModelID` instead, and `ModelContext` is not `Sendable` either. In Swift 6 language mode, returning a model from a `@ModelActor` method to main-actor code is a compile error. The fix is to send `model.persistentModelID`, a `PersistentIdentifier` that is `Sendable`, `Hashable` and `Codable`, and look the model up in the receiving context: `mainContext.model(for:)`, `registeredModel(for:)`, or `self[id, as:]` inside a model actor. Save before you send it: an inserted model has a **temporary** identifier until its first save, and iOS 27 adds `isTemporary` so you can check.

code

swift · 30 lines
swift
import SwiftData
import Foundation

@Model final class Inspection {
    var siteName: String
    var isReviewed = false
    init(siteName: String) { self.siteName = siteName }
}

@ModelActor
actor InspectionWorker {
    func createDraft(siteName: String) throws -> PersistentIdentifier {
        let draft = Inspection(siteName: siteName)
        modelContext.insert(draft)
        try modelContext.save()          // the identifier is permanent after this
        return draft.persistentModelID   // Sendable, unlike the model
    }

    func markReviewed(_ id: PersistentIdentifier) throws {
        guard let inspection = self[id, as: Inspection.self] else { return }
        inspection.isReviewed = true
        try modelContext.save()
    }
}

@MainActor
func openDraft(container: ModelContainer, worker: InspectionWorker) async throws -> Inspection? {
    let id = try await worker.createDraft(siteName: "Bridge 12")
    return container.mainContext.model(for: id) as? Inspection
}

go deeper

for a junior

Remember that SwiftData models stay inside the context and actor that loaded them, and that you pass persistentModelID instead.

for a middle

Explain the unavailable Sendable conformances on models and contexts and the three ways to load a model from an identifier.

for a senior

Catch identifiers returned before a save, model(for:) used as an existence check, and models captured by detached tasks; know what Swift 6 mode reports and Swift 5 mode hides.

for a principal

Set a team rule that actor and service APIs exchange identifiers or value types, never models, and enforce it with Swift 6 language mode.

## Why a model cannot cross A SwiftData model object is a reference type whose stored values are managed by the **one `ModelContext`** it is registered with. Two isolation domains touching the same object could race on that context's state, so SwiftData blocks it at compile time: - The `@Model` macro generates an extension that declares the class's `Sendable` conformance **unavailable**, with the message "PersistentModels are not Sendable, consider utilizing a ModelActor or use Inspection's persistentModelID instead" (with your type's name). - `ModelContext`'s `Sendable` conformance is likewise unavailable: "contexts cannot be shared across concurrency contexts". In **Swift 6 language mode** these become hard errors. Returning a model from a `@ModelActor` method to `@MainActor` code fails with "non-Sendable 'Inspection'-typed result can not be returned from actor-isolated instance method ... to main actor-isolated context". In Swift 5 mode with default checking the same code compiles, and the model is then used from two isolation domains, which is exactly the race the annotations exist to prevent. ## The identifier is the thing to send Every model has `persistentModelID`, a `PersistentIdentifier`. It is a struct that is `Sendable`, `Hashable`, `Comparable` and `Codable`, carrying the entity name and, as a property, the identifier of the store it lives in. Send that, and let each side load **its own** model object from **its own** context: | Where you are | How to load | What you get when the context doesn't know the identifier | |---|---|---| | Any `ModelContext` | `model(for:)` | A non-optional model; the documentation says an unsaved model carrying that identifier | | Any `ModelContext` | `registeredModel(for:)` | `nil`: it only returns models already registered in that context | | Inside a `@ModelActor` | `self[id, as: Inspection.self]` | An optional, `T?`, typed to the model | Because `model(for:)` never returns `nil`, it cannot tell you that an identifier is stale; cast the result and, when existence matters, check it with a fetch, which is covered with querying and fetching. ## Temporary identifiers Apple's documentation for `insert(_:)` says a model gets a **temporary** persistent identifier until the first time a context saves it; the save assigns a permanent one. If a model actor inserts a draft and returns its identifier **before** saving, the main context receives an identifier no stored row matches. The rule: 1. Insert the model in the actor's context. 2. Call `save()`. 3. Return `model.persistentModelID`. From **iOS 27**, `PersistentIdentifier.isTemporary` reports whether an identifier is still temporary, which makes a cheap assertion before sending one across. ## Handing over many models To pass a whole result set, send an array of identifiers, which is `Sendable` because its elements are. `ModelContext.fetchIdentifiers(_:)` returns only the identifiers of the models that match a fetch, without the overhead of loading their data, which suits an actor that decides *which* models the UI should show while the main context loads only the ones on screen. ## Scope of an identifier - A `PersistentIdentifier` is meaningful **within the local store**. Apple's history documentation notes that a model's identifier is only relevant within the scope of the local data store; for identity across devices or a server, keep your own stable attribute such as the server's record ID. - Because it is `Codable`, you can persist an identifier locally, for example to restore a selection, but treat a lookup that finds nothing as a normal case: the model may have been deleted. ## Mistakes to catch in review - An actor method whose return type is a model or an array of models. - A `Task.detached` closure that captures a model or a context. - An identifier returned before the save that makes it permanent. - `model(for:)` treated as a check that the model still exists. - A persistent identifier sent to a server as the record's identity. The general rules of `Sendable` and region-based isolation belong to the Swift language material on concurrency; this topic is how SwiftData applies them to models and contexts.

  • What is the practical difference between model(for:) and registeredModel(for:) on SwiftData's main context?
    `registeredModel(for:)` returns the typed model only if that context already has it registered, otherwise `nil`. `model(for:)` always returns a model; Apple's documentation says that for an identifier the context does not know, it is an unsaved model carrying that identifier. Use the first for a cheap is-it-loaded check and the second to obtain a model to work with.
  • Why does the code compile in Swift 5 mode but not in Swift 6 mode?
    SwiftData's unavailable `Sendable` conformances make models and contexts non-`Sendable` in both modes, but Swift 5 mode with default checking does not diagnose region-isolation crossings. Swift 6 language mode makes them errors, and `-strict-concurrency=complete` shows them as warnings in Swift 5 mode.
  • Can you store a PersistentIdentifier and use it after the app relaunches?
    It is `Codable`, so you can encode a saved, permanent identifier and look it up later in the same local store. Treat a missing model as normal, since it may have been deleted, and never use it as identity on a server or another device.

A library lends you a call number, not the shelf: you carry the number to another branch and that branch fetches its own copy. A number written down before the book was catalogued points at nothing.

  • The @Model macro makes model classes Sendable, so returning them from an actor is fine.
  • Wrapping a model in a Task makes it safe to share across actors.
  • model(for:) returns nil when the model no longer exists.
  • An identifier is permanent the moment the model is inserted.
  • persistentModelID is a good identity to sync with the server.

Assumes the iOS 27 SDK; PersistentIdentifier.isTemporary is new in iOS 27, while sending identifiers instead of models works from iOS 17.