This topic describes the behavior of the Xbox One operating system when a title’s installation from over the network or from optical media fails. The intended audience of this paper is systems engineers developing Xbox One titles.
There are a number of circumstances that can cause a title’s streaming installation to fail. The exact nature of the failure depends on which data source is being used for the title’s installation.
Why an installation from a Blu-ray disc could fail:
Why an installation over the network could fail:
The system automatically retries copying data from the title package source—Blu-ray disc or network—repeatedly until it gives up. The exact number of retries and amount of time before the system gives up are system-defined and subject to change.
When the retry phase expires, a system notification is shown to the user alerting that the installation has failed. The user can then view the title in the collection to investigate options to recover/retry.
If the user restarts the title, a new installation attempt starts automatically.
By default, titles install from the top to the bottom of their installation package layout file. Some titles may choose to override this ordering and provide their own ordering.
If the installer is retrying a chunk that it cannot read when the title tells it to immediately install a different chunk, the retry count is reset, and the installation attempts to install the new chunk.
However, you should not rely on this behavior to fully address the failure. Even if the title re-orders installations to avoid damaged/irretrievable chunks, the installation process will eventually run out of chunks to install or revert to the default installation order. When this occurs, the installer eventually hits the damaged chunk again, stops the process, and shows the user a notification.
The PackageTransferManager.TransferStatus Property indicates the current state of the installer. Its values are declared by the PackageTransferStatus Enumeration:
| State | Description |
|---|---|
| None | No installer activity is scheduled. It has already completed successfully. |
| Waiting | The system is busy, and the installer is waiting to run. The current title is not actively installing. |
| Paused | The install has been paused by the user. |
| Running | The install is actively working. |
| Error | The installer detected an error, and has been halted. |
If your code is monitoring the installation and determines that it has taken too long for a chunk to install, check the TransferStatus value to see if the installation has been stopped, been paused, or encountered an error. If the installer is no longer in the Running or Paused state, you should take action to mitigate this for the user. Some ideas about how to handle a halted installation are listed below.
You should examine the TransferStatus property once per frame at most. Ideally, you should check it only when a chunk takes longer than your title expects or if the user tries to initiate an action that cannot be performed until the chunk is present.
Network installations and download times can vary considerably; applying a simple timeout may lead to false failures. If you have a watchdog for chunk installation and TransferStatus returns Running, you should continue waiting for the chunk and handle the delay in your title code. Do not assume that it has failed.
Even if an installation fails, the failure may not necessarily prevent the user from playing your title. If you have enough valid content to proceed, you can allow your users to play.
Options for handling a halted installation include:
The exact behavior to use for your title is depends largely on its design, and involves similar choices and trade-offs for designing the title around streaming install. The same strategies you need to employ for slow network downloads on a network-only installation apply in the extreme case of installations that might never complete during this gameplay session.