{"record":{"id":"c419d204fd18b278","repo":"Unity-Technologies/UnityCsReference","slug":"the-build-cannot-be-appended","errorCode":null,"errorMessage":"The build cannot be appended.","messagePattern":"The build cannot be appended\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/BuildPipeline/BuildPipeline.bindings.cs","lineNumber":221,"sourceCode":"\n            if (buildPlayerOptions.targetGroup == BuildTargetGroup.Unknown)\n                buildPlayerOptions.targetGroup = GetBuildTargetGroup(buildPlayerOptions.target);\n\n            string locationPathNameError;\n            if (!ValidateLocationPathNameForBuildTarget(buildPlayerOptions.locationPathName, buildPlayerOptions.target, buildPlayerOptions.subtarget, buildPlayerOptions.options, out locationPathNameError))\n                throw new ArgumentException(locationPathNameError);\n\n            string scenesError;\n            if (!ValidateScenePaths(buildPlayerOptions.scenes, out scenesError))\n                throw new ArgumentException(scenesError);\n\n            if ((buildPlayerOptions.options & BuildOptions.AcceptExternalModificationsToPlayer) == BuildOptions.AcceptExternalModificationsToPlayer)\n            {\n                CanAppendBuild canAppend = BuildCanBeAppended(buildPlayerOptions.target, buildPlayerOptions.locationPathName);\n                if (canAppend == CanAppendBuild.Unsupported)\n                    throw new InvalidOperationException(\"The build target does not support build appending.\");\n                if (canAppend == CanAppendBuild.No)\n                    throw new InvalidOperationException(\"The build cannot be appended.\");\n            }\n\n            if (buildPlayerOptions.scenes != null)\n            {\n                for (int i = 0; i < buildPlayerOptions.scenes.Length; i++)\n                    buildPlayerOptions.scenes[i] = buildPlayerOptions.scenes[i].Replace('\\\\', '/').Replace(\"//\", \"/\");\n            }\n\n            if ((buildPlayerOptions.options & BuildOptions.Development) == 0)\n            {\n                if ((buildPlayerOptions.options & BuildOptions.AllowDebugging) != 0)\n                {\n                    throw new ArgumentException(\"Non-development build cannot allow debugging. Either add the Development build option, or remove the AllowDebugging build option.\");\n                }\n\n                if ((buildPlayerOptions.options & BuildOptions.EnableCodeCoverage) != 0)\n                {\n                    throw new ArgumentException(\"Non-development build cannot allow code coverage. Either add the Development build option, or remove the EnableCodeCoverage build option.\");","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/BuildPipeline/BuildPipeline.bindings.cs#L203-L239","documentation":"Thrown when BuildPlayer is called with BuildOptions.AcceptExternalModificationsToPlayer on a platform that conceptually supports appending, but the existing export at locationPathName cannot be appended to. BuildCanBeAppended returns CanAppendBuild.No when the target directory is missing, was produced by a different Unity version, or is in an inconsistent state.","triggerScenarios":"Calling BuildPipeline.BuildPlayer with AcceptExternalModificationsToPlayer on Android/iOS when the locationPathName directory either doesn't exist yet, was built by an incompatible Unity version, or has been modified/corrupted since the last export.","commonSituations":"First incremental export to a directory that was deleted, CI builds on clean agents where the export folder is ephemeral, upgrading Unity major versions and trying to append to an old export, or manually editing the exported project between builds.","solutions":["Delete the existing export directory and do a clean export (first append to a fresh location always succeeds).","Verify the locationPathName points to a valid prior export created by the same Unity version before enabling AcceptExternalModificationsToPlayer.","In CI, run a full clean build on the first run of a new Unity version, then switch to incremental for subsequent runs."],"exampleFix":"// before\nvar options = new BuildPlayerOptions\n{\n    locationPathName = \"./AndroidExport\",\n    options = BuildOptions.AcceptExternalModificationsToPlayer,\n    target = BuildTarget.Android\n};\nBuildPipeline.BuildPlayer(options); // fails if ./AndroidExport is stale or missing\n\n// after\nstring exportDir = \"./AndroidExport\";\nif (!Directory.Exists(Path.Combine(exportDir, \"build.gradle\")))\n{\n    if (Directory.Exists(exportDir))\n        Directory.Delete(exportDir, recursive: true);\n}\n\nvar options = new BuildPlayerOptions\n{\n    locationPathName = exportDir,\n    options = BuildOptions.AcceptExternalModificationsToPlayer,\n    target = BuildTarget.Android\n};\nBuildPipeline.BuildPlayer(options);","handlingStrategy":"validation","validationCode":"bool IsAppendSafe(string exportDir, BuildTarget target)\n{\n    if (target != BuildTarget.Android && target != BuildTarget.iOS)\n        return false;\n    // Android: check for gradle project marker; iOS: check for .xcodeproj or Unity-iPhone.xcodeproj\n    return Directory.Exists(exportDir) &&\n        Directory.GetFiles(exportDir, \"build.gradle\", SearchOption.TopDirectoryOnly).Length > 0;\n}\n\n// Before BuildPlayer with AcceptExternalModificationsToPlayer:\nif (!IsAppendSafe(options.locationPathName, options.target))\n{\n    if (Directory.Exists(options.locationPathName))\n        Directory.Delete(options.locationPathName, recursive: true);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["On CI, start with a clean export directory for the first incremental build after a Unity upgrade.","Never manually modify an exported Android/iOS project between incremental builds.","Verify the export directory contains expected project structure markers before enabling append."],"tags":["unity","build-pipeline","build-append","android","ios","incremental-build"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}