Unity-Technologies/UnityCsReference · error · BuildFailedException

Failed to add player icon

Error message

Failed to add player icon

What it means

Thrown as BuildFailedException when postprocessor.AddIconsToBuild(args) returns false, meaning the platform post-processor could not supply the required player icon(s) into the staging area for the build.

Source

Thrown at Editor/Mono/BuildPipeline/PostprocessBuildPlayer.cs:349

            string stagingAreaDataManaged = "Temp/StagingArea/Data/Managed";
            string playerPackage = BuildPipeline.GetPlaybackEngineDirectory(target, options);

            // Disallow providing an empty string as the installPath
            bool willInstallInBuildFolder = (options & BuildOptions.InstallInBuildFolder) != 0 && SupportsInstallInBuildFolder(target);
            if (installPath == String.Empty && !willInstallInBuildFolder)
                throw new Exception(installPath + " must not be an empty string");

            IBuildPostprocessor postprocessor = ModuleManager.GetBuildPostProcessor(target);
            if (postprocessor == null)
                // If postprocessor is not provided, build target is not supported
                throw new UnityException($"Build target '{target}' not supported");

            try
            {
                AddIconsArgs iconArgs;
                iconArgs.stagingArea = stagingArea;
                if (!postprocessor.AddIconsToBuild(iconArgs))
                    throw new BuildFailedException("Failed to add player icon");

                BuildPostProcessArgs args;
                args.target = target;
                args.subtarget = subtarget;
                args.stagingAreaData = stagingAreaData;
                args.stagingArea = stagingArea;
                args.stagingAreaDataManaged = stagingAreaDataManaged;
                args.playerPackage = playerPackage;
                args.installPath = installPath;
                args.companyName = companyName;
                args.productName = productName;
                args.productGUID = PlayerSettings.productGUID;
                args.options = options;
                args.usedClassRegistry = usedClassRegistry;
                args.report = report;
                args.defineConstraints = defineConstraints;

                BuildProperties props;

View on GitHub (pinned to 225b0fbdb5)

Solutions

  1. Assign a valid Default Icon in Player Settings and ensure platform icon slots are filled with correctly sized, readable textures.
  2. Verify icon textures are imported as Sprite/Editor or GUI with Read/Write enabled if the platform requires it.
  3. Check the post-processor logs for the specific icon slot that failed and fix that asset.

Example fix

/* no source edit; project fix */
// before: Player Settings > Default Icon empty / invalid texture -> AddIconsToBuild returns false
// after: assign a valid readable Texture2D as Default Icon and per-platform icons, then rebuild
Defensive patterns

Strategy: validation

Validate before calling

// Validate icons before building
if (PlayerSettings.GetIconsForTargetGroup(buildTargetGroup).Any(t => t == null))
    Debug.LogWarning("Some platform icons are unassigned; AddIconsToBuild may fail.");

Try / catch

try { PostprocessBuildPlayer.Postprocess(...); }
catch (BuildFailedException ex) when (ex.Message == "Failed to add player icon")
{ Debug.LogError("Fix Player Settings icons and rebuild."); throw; }

Prevention

When it happens

Trigger: Postprocess calls AddIconsToBuild and the target's IBuildPostprocessor reports failure (missing icon texture, wrong icon size/format, icon settings invalid for the platform).

Common situations: Player Settings > Default Icon not assigned or texture not readable/imported correctly; platform-specific icon slot (e.g. Android adaptive icon, iOS icon set) missing or wrong resolution; icon asset deleted after being referenced.

Related errors

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/eeadb5db57169ae4. Report an issue: GitHub.