Use the following information to help find solutions to common crashes and other problems when running your Unity application on iOS devices.
Note: If your issue persists after troubleshooting, refer to Report crash bugs for iOS.
The following list provides some common reasons for this issue:
List<int>
, List<SomeStruct>
, List<SomeEnum>
for serialized script properties.Information from the Xcode debugger console can often help detect these problems. Access the debugger console from View > Debug Area > Activate Console.
This message typically appears on iOS devices when your application receives a NullReferenceException
. Use native stack traces to find out where the fault occurred.
Native stack traces are a useful tool for fault investigation, but using them requires some expertise. You generally can’t continue after these hardware memory access faults happen. To access a native stack trace, type bt all
into the Xcode debugger console. Inspect the printed stack traces as they can contain information about where the error occurred. For example, a typical stack trace might look like this:
...
Thread 1 (thread 11523):
1. 0 0x006267d0 in m_OptionsMenu_Start ()
1. 1 0x002e4160 in wrapper_runtime_invoke_object_runtime_invoke_void__this___object_intptr_intptr_intptr ()
1. 2 0x00a1dd64 in mono_jit_runtime_invoke (method=0x18b63bc, obj=0x5d10cb0, params=0x0, exc=0x2fffdd34) at /Users/mantasp/work/unity/unity-mono/External/Mono/mono/mono/mini/mini.c:4487
1. 3 0x0088481c in MonoBehaviour::InvokeMethodOrCoroutineChecked ()
...
Locate the stack trace for “Thread 1”, which is the main thread. The initial lines of the stack trace will point to the place where the error occurred. In this example, the trace indicates that the NullReferenceException
happened inside the _OptionsMenu_
script’s _Start_
method. Inspecting this method implementation can help reveal the cause of the problem. Typically, NullReferenceExceptions happen inside the _Start_
method when incorrect assumptions are made about initialization order.
Sometimes only a partial stack trace is displayed in the debugger console. For example:
Thread 1 (thread 11523):
1. 0 0x0062564c in start ()
This message indicates that native symbols were stripped during the release build of the application. To investigate further, access the full stack trace using the following steps:
You might encounter a warning message like Program received signal: "0"
. This warning message is often not fatal, and indicates that iOS is low on memory. Typically, background processes like Mail will free some memory and your application can continue to run. However, if your application continues to use memory or ask for more, iOS will start terminating applications including your own. Apple doesn’t document what memory usage is safe, but observations have shown that applications using less than 50% of all device RAM don’t have major memory usage problems.
The main metric to use is how much RAM your application uses. Your application memory usage consists of the following components:
Component | Description |
---|---|
Application code | The OS needs to load and keep your application code in RAM, but some of it might be discarded if required. |
Native heap | Used by the engine to store its state and your assets in RAM. |
Managed heap | Used by your il2cppA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info See in Glossary runtime to store C# objects. |
Metal memory pools | Used to store Textures, framebuffers, and compiled shadersA program that runs on the GPU. More info See in Glossary. |
You can track application memory usage in Xcode. For more information, refer to Gathering information about memory use (Apple Developer).
To keep memory usage low, use the following suggestions:
Querying the OS about the amount of free memory might seem to be the most efficient way to evaluate how well your application is performing. However, the free memory statistic is likely to be unreliable as the OS uses a lot of dynamic buffers and caches. It’s recommended to keep track of memory consumption for your application and use that as the main metric, combined with the Xcode memory tools especially after loading new scenesA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary.
It’s recommended to inspect the device logs to get more details. To do this, use the following steps:
You might also need to investigate crash reports. For more information, refer to Acquiring crash reports and diagnostic logs (Apple Developer).
There’s a set time limit to allow an iOS application to render the first frames and process input. If your application exceeds this limit, it is terminated by SpringBoard. For example, this can happen in an application where the size of the first scene is too large. It’s recommended to create a small initial scene with a splash screen, wait for a few frames, and then proceed to load the larger scene. To achieve this, use the following example:
IEnumerator Start() {
yield return new WaitForEndOfFrame();
// Do not forget using UnityEngine.SceneManagement directive
SceneManager.LoadScene("Test");
}
.NET Cryptography services aren’t compatible with managed code stripping. These services rely on reflection, whereas managed code stripping involves static code analysis. The stripping process can be customized by adding a custom link.xml
file to the Assets
folder of your Unity project. This specifies the types and namespaces to exclude from stripping. Exclude the System.Security.Crypography
namespace from the stripping process to help resolve this issue. For example, add the following to the link.xml
file:
<linker>
<assembly fullname="mscorlib">
<namespace fullname="System.Security.Cryptography" preserve="all"/>
</assembly>
</linker>
You can resolve this issue in the same way as outlined in the previous section, or you can add extra references to specific classes to your script code. To do this, use the following example:
object obj = new MD5CryptoServiceProvider();
Some operations within the UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary will result in iOS redrawing the window immediately. The most common example is adding a UIView with a UIViewController to the main UIWindow. If calling a native function from a script, it will happen inside Unity’s PlayerLoop, resulting in the PlayerLoop being called recursively. When this occurs, you will receive the error message PlayerLoop called recursively!
. In such cases, consider using the performSelectorOnMainThread (Apple Developer) method with waitUntilDone
set to false. It will inform iOS to schedule the operation to run between Unity’s PlayerLoop calls.
To diagnose this issue, use the following suggestions:
225.0.0.222
on UDP port 54997
. Check that your network settings allow this traffic. The profiler will also make a connection to the remote device on a port in the range 55000 - 55511
to fetch profiler data from the device. These ports will need to be open for TCP access.This issue is caused when the built machine code is too large and has hit Xcode limitations. This can occur if you have lots of script code, or are using large external .NET assemblies in a build. Using the Script Debugging build setting can also add to this issue, as it creates additional instructions for each function.
To assist with this issue, in the Unity Editor navigate to Edit > Project Settings > Player > iOS and try one or more of the following options:
If the issue persists, it’s recommended to split user script code into multiple assemblies. For example, the Plugins
folder can be used to place any split code as code at this location is added to a different assembly. It’s also recommended to refer to Special folders and script compilation order for information on how special folder names affect script compilation.
Starting with Xcode version 14.3, Apple introduced the Destination Architecture option. With Destination Architecture, you can use iOS simulators on ARM-based Macs without the need to run Xcode in Rosetta simulator mode.
To view the iOS simulators, use the following steps:
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.