Circular Reference Error in Xcode 26

I have my project running perfectly fine on Xcode 16. However, in Xcode 26 it doesn't build due to an error that I do not understand. I have three files that pertain to this error:

// FriendListResponse.swift

import Foundation

struct FriendListResponse: Decodable {
    var friendships: [Friendship]
    var collections: [FriendCollection]
}
// Friendship.swift

import Foundation

struct Friendship: Decodable {
    var createdAt: String
    var friendId: Int
    var friendUserId: Int  // user ID of the friend
    var friendUsername: String
    var id: Int
    var tagNames: [String]
}
// FriendCollection.swift

struct FriendCollection: Decodable {
    var id: Int
    var permalink: String
    var tagNames: [String]
    var title: String
}

On the first file, FriendListResponse.swift, I am the simple error message "circular reference." I do not understand how these self-contained structs could create a circular reference. Although I have other data types in my project, none of them are even referenced in these files except for Friendship and FriendCollection.

The FriendListResponse is a struct that is created from JSON values that are fetched from an API. This is the function that fetches the JSON:

public static func listFriends(username: String) async throws -> [Friendship] {
        let data = try await sendGETRequest(
            url: "people/\(username)/friends/list.json"
        )
        print(String(data: data, encoding: .utf8)!)
            
        let decoder = JSONDecoder()
        decoder.keyDecodingStrategy = .convertFromSnakeCase
        let wrapper = try decoder.decode(FriendListResponse.self, from: data)
        return wrapper.friendships
}

// Note: the function sendGETRequest is just
// a function that I have created that takes a set
// of parameters and returns a data object
// using the HTTP GET protocol. I don't think 
// that it is related to this issue. However, if you
// think that it is, I can share the code for that.

This error has also happened in a few other cases within contained networks of my data structure.

I do not know why this error is only appearing once I launch Xcode 26 beta with my project files. I would think that this error also would appear in Xcode 16.4.

Any help would be greatly appreciated in my process to compile my project on Xcode 26!

Answered by DTS Engineer in 846719022

FYI, I’ve confirmed that the rogue circular reference diagnostic is a bug, but the fix missed the Xcode 26.0b2 bus. See here.

as I potentially integrate more concurrency later in development, will there be any issues directly stemming from using nonisolated as opposed to MainActor?

Potentially? Of course.

This is one of those ‘everything in engineering is a trade-off’ situations. You have two options, both of which you can make work, but it’s hard to know for such which will be the best in the long term.

My general advice for app developers is to do everything on the main actor until you have hard evidence that you need something else [1]. Given that, I’d probably use the main actor conformance approach, rather than the nonisolated approach. However, I can in no way guarantee that you won’t need to change that as your app evolves.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] This has been my policy for many years, since long before Swift concurrency, or even Swift! I’m very happy to see that it’s now aligned with Swift’s approachable concurrency effort.

I tried reproducing this but couldn’t. Specifically:

  1. Using Xcode 26.0 beta on macOS 15.5, I created a new test project from the iOS > App template.

  2. I added files FriendListResponse.swift, Friendship.swift, and FriendCollection.swift, and populated them with the text you posted.

  3. I was able to build the project just fine.

Can you share a test project that reproduces the issue?

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

I rebuilt the project in Xcode 26.0 beta 2 using the iOS 26 beta 2 SDK and the issue persists. I tried to create a test project. However, I was not able to keep it within reasonable size and not include my entire codebase to reproduce the issue. Therefore, I am not quite sure what is causing this "circular reference issue" because, at surface level, there doesn't seem to be a circular reference of any kind in my data structures.

Could this be a bug with the beta Xcode or SDKs as this is not an issue in Xcode 16? Have there been any changes from iOS 18->26 or Xcode 16-> 26 that change the Swift Compiler regarding circular references?

Accepted Answer

I tried reproducing this but couldn’t.

Having seen the error myself, I could reproduce it as follows:

  1. Paste the three structs from the op's original post into a Swift file in a new app project.

  2. Change "Decodable" for each to "Codable" (I couldn't reproduce it for "Decodable" only for some reason).

  3. Make sure that strict concurrency checking is set to "Complete" and "MainActor" is set as the default actor isolation for the project.

When I do this, I see a "Circular reference" error with several "Through reference here" comments that don't make much sense.

There seem to be two possible fixes depending on how the struct is intended to be used:

  1. Explicitly set the struct as "nonisolated" (which prior to the change in default actor isolation would have been the default):

nonisolated struct FriendListResponse: Codable

  1. Force the conformance to @MainActor:

struct FriendListResponse: @MainActor Codable

(Note that the second solution will break if you use custom codingKeys, however, even if you try to force the conformance on that to @MainActor - not sure why.)

I hasten to add that my knowledge of Swift 6 and concurrency is wanting - I'm only starting to explore migration from Swift 5 to Swift 6 and understanding the errors involved, so apologies to the op if this is unhelpful.

Adding nonisolated to my struct fixed the issue. My project is, as well, on MainActor default isolation mode. Although this fixes the problem, I am not sure about any repercussions that this might have in terms of concurrency. I am also new to Swift concurrency (I found Embracing Swift Concurrency from WWDC25 to be very helpful if you haven't watched it already).

However, I am not sure if this is intended functionality or not because the error gives very little information.

Thanks for your solutions!

Having seen the error myself, I could reproduce it as follows:

Oh, interesting. I tried your steps and was able to reproduce the problem. Nice.

I was then able to distill it down much further:

  1. With Xcode 26.0b2, I created a new project from the macOS > Command Line Tool template.

  2. I set Swift Language Version to 6. This isn’t mandatory, but it’ll make it easier for me to explain what’s going on.

  3. I set Strict Concurrency Checking to Complete.

  4. And Default Actor Isolate to MainActor.

  5. And added this main.swift:

    struct FriendListResponse: Codable {
    }
    

So, are two errors being reported here. The first is:

struct FriendListResponse: Codable {
                           ^ Conformance of 'FriendListResponse' to 
                             protocol 'Encodable' crosses into main 
                             actor-isolated code and can cause data 
                             races
}

The code as its stands is problematic because FriendListResponse is isolated to the main actor (via step 4) but Codable implies that it must not be so isolated.

The second error is the circular reference stuff. AFAICT that’s just a compiler bug. I suspect it’s triggered by the first error, that is, the act of handling the first error sends the compiler off into the weeds and generates the second one. However, that’s just speculation. I’ve filed my own bug about this diagnostic (r. 154484420).

As KeithB noted, there are two paths forward here:

  • You can isolate the Codable conformance to the main actor.

  • You can deassociate FriendListResponse from the main actor.

The best option depends on how you intend to use FriendListResponse. If you wanna elaborate on that, I’d be happy to offer my opinion.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

After my first time building my code in Xcode 26, I got the first error that you mentioned. So, because I was not using the Encodable part of the Codable conformance, I simply switched it to Decodable and it made that error go away but kept the circular reference bug.

Then, I followed KeithB's solution and added nonisolated to each struct that was throwing that error. I am new to Swift Concurrency and don't really know what repercussions this change could have on my codebase and concurrency (I assumed that it wouldn't be critical because of Swift's data race safety).

I am using these structs as a way to decode JSON into a struct from an HTTP GET/POST API. I am sending a request to the web service and receive the JSON in exchange. I use the built-in JSONDecoder to decode. All of the JSON processing runs in an asynchronous function so that it doesn't cause any hangs in my app.

As of right now, with KeithB's solution, my app is working fine but as I potentially integrate more concurrency later in development, will there be any issues directly stemming from using nonisolated as opposed to MainActor?

FYI, I’ve confirmed that the rogue circular reference diagnostic is a bug, but the fix missed the Xcode 26.0b2 bus. See here.

as I potentially integrate more concurrency later in development, will there be any issues directly stemming from using nonisolated as opposed to MainActor?

Potentially? Of course.

This is one of those ‘everything in engineering is a trade-off’ situations. You have two options, both of which you can make work, but it’s hard to know for such which will be the best in the long term.

My general advice for app developers is to do everything on the main actor until you have hard evidence that you need something else [1]. Given that, I’d probably use the main actor conformance approach, rather than the nonisolated approach. However, I can in no way guarantee that you won’t need to change that as your app evolves.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] This has been my policy for many years, since long before Swift concurrency, or even Swift! I’m very happy to see that it’s now aligned with Swift’s approachable concurrency effort.

Circular Reference Error in Xcode 26
 
 
Q