Unity Cloud Build Fails - Continuous Integration Fix

Problem: Unity Cloud Build (or your Unity-based continuous integration pipeline) fails: builds time out, fail with scripting errors, missing dependencies, or credential issues. You may see errors in the Cloud Build dashboard or in your CI logs such as "Build failed", "Script compilation error", "Out of memory", or "Credentials invalid".

Root cause: Cloud Build and CI failures usually come from one of these: project or build settings that differ from your local setup (e.g. missing defines, wrong platform); scripting or assembly errors that only show in a clean build; missing or private dependencies (packages, Git submodules, secrets) the build agent cannot access; credentials (e.g. Unity account, version control, or API keys) not configured for the build environment; or resource limits (time, memory) on the build host. Fixing them means aligning project settings, verifying the build from a clean clone, and ensuring the build service has everything it needs.

This guide walks you through the most common fixes step by step. Apply them in order; many failures are resolved by matching Cloud Build configuration to your project and fixing compilation or dependency issues first.

Quick fix checklist

Build from a clean clone – Reproduce the build locally from a fresh clone (no Library/cache) to catch scripting and dependency errors.
Project and build settings – Ensure target platform, scripting backend, API level, and custom defines match what Cloud Build uses.
Dependencies and packages – Lock package versions, include manifest and lock file, and avoid private or unreachable feeds without credentials.
Credentials and secrets – Configure Unity account, version control, and any API keys in the Cloud Build or CI environment.
Time and memory – Increase build timeout or agent size if the project is large; fix scripts that cause out-of-memory in the build.

Solution 1: Reproduce the build locally (clean build)

Problem: The build fails on Cloud Build but works on your machine, so the cause is environment or cache-related.

Step 1: Clone the project into a new folder

Use a new clone from your version control (Git, Plastic, etc.) so there is no local Library or Temp from your main copy.
This simulates what the build agent sees: only what is committed.

Step 2: Open in Unity and build for the same target

Open the project in the same Unity version as Cloud Build (check Cloud Build build settings).
Use File → Build Settings, select the same platform (e.g. Android, iOS, Windows), and Build (or Build And Run).
Do not copy Library from another machine; let Unity generate it.

Step 3: Fix any errors that appear

If the clean build fails locally with compilation errors, missing assemblies, or missing references, fix those first.
Common issues: Assembly Definition references to packages or other asmdefs that are not in the repo; missing or private packages; code that depends on local paths or editor-only data.
Commit the fixes and re-run Cloud Build.

Verification: A successful local build from a clean clone does not guarantee Cloud Build will succeed, but it removes most scripting and project-structure causes. If Cloud Build still fails, move to Solution 2.

Solution 2: Align project and build settings

Problem: Cloud Build uses different platform, scripting backend, or API level than you expect, or custom defines are missing so code paths fail.

Step 1: Check Cloud Build build target and version

In Unity Dashboard → Cloud Build (or your CI config), confirm the Unity version and build target (e.g. Android, iOS, StandaloneWindows64).
Ensure they match what you use locally for that platform. Mismatches can cause different compilation or linking behavior.

Step 2: Match scripting backend and API level

For Android, Cloud Build must use the same Scripting Backend (Mono vs IL2CPP) and Target API Level as in Player Settings.
For iOS, check Target minimum iOS version and Architecture.
Set these in Edit → Project Settings → Player → [Platform] and commit; Cloud Build reads from the project.

Step 3: Custom defines and version stripping

If your code uses Scripting Define Symbols, ensure they are set in Player Settings for the correct platform.
If Cloud Build uses a different build type (e.g. Development vs Release), defines or code guarded by UNITY_EDITOR or DEBUG may behave differently; account for that in your scripts.

Step 4: Build hooks (optional)

If you use Pre-export or Post-export build steps (e.g. Cloud Build build hooks), ensure they run in the same order and with the same inputs as in your docs. A failing hook can break the build; test it locally if possible.

Verification: After aligning settings, trigger a new build. If the failure message changes or you get past compilation, continue to Solution 3 for dependencies and credentials.

Solution 3: Dependencies and packages

Problem: The build fails because a package, Git submodule, or asset is missing or not available to the build agent.

Step 1: Commit manifest and lock file

Packages/manifest.json (and Packages/packages-lock.json if present) must be in version control so the build agent restores the same package set.
Do not rely on local-only package cache; the agent resolves from manifest.

Step 2: Avoid private or unlisted packages without auth

If you use a private or scoped registry, the build environment must have credentials (e.g. .npmrc or Unity’s package manager auth). Configure them in Cloud Build Environment or Secrets and ensure the agent can reach the registry.
Prefer embedded or local packages in the repo for CI so the agent does not need extra network access.

Step 3: Git submodules and large assets

If the project uses Git submodules, ensure Cloud Build is configured to clone submodules (e.g. git clone --recurse-submodules or equivalent in the CI config).
Large binary assets can cause timeouts or storage issues; use Git LFS and ensure the build agent has LFS enabled and sufficient quota.

Step 4: Assembly Definition references

Assembly Definition files must reference only assemblies the build can resolve: other asmdefs in the project or packages from manifest.
References to assemblies that exist only in your local Library (e.g. from a locally installed package) will break in CI; move the dependency into manifest or an in-repo asmdef.

Verification: After fixing dependencies, run a clean build again locally, then re-run Cloud Build. If the error is about credentials or permissions, go to Solution 4.

Solution 4: Credentials and secrets

Problem: Build fails with authentication or permission errors: Unity login, version control, or API keys are missing or invalid in the build environment.

Step 1: Unity account and license

Unity Cloud Build uses the Unity account linked to the project. Ensure the organization or project has a valid Unity license (Personal, Plus, Pro) and that the build service is allowed to use it.
If you use a custom CI (e.g. GitHub Actions with Unity runner), the runner must activate Unity with a license; use a license that supports headless/CI use.

Step 2: Version control access

The build agent must clone your repo. For private repos, configure SSH keys, personal access tokens, or CI credentials in the Cloud Build or CI environment.
Do not hardcode credentials in the project; use the CI’s secret or environment variable mechanism.

Step 3: Third-party API keys or SDKs

If the build process needs API keys (e.g. for analytics, ads, or backend), inject them via environment variables or CI secrets and read them in build scripts or Player Settings (e.g. custom defines) so they are not committed.
For Android/iOS, ensure keystore or provisioning credentials are configured in Cloud Build or your CI; otherwise signing can fail.

Verification: After configuring credentials, trigger a new build. If the failure is timeout or out-of-memory, see Solution 5.

Solution 5: Build timeout and out-of-memory

Problem: Build runs for a long time then fails with "timeout" or "out of memory" (OOM).

Step 1: Increase build timeout

In Cloud Build or your CI, increase the build timeout so large projects have enough time to compile and package.
Reduce unnecessary work in the build (e.g. skip heavy tests in the same job if they are in a separate pipeline).

Step 2: Reduce memory use during build

IL2CPP and Burst compilation can use a lot of memory. On agents with limited RAM, try Mono for a test build to see if OOM disappears, then consider a larger build agent or splitting the build.
Disable or defer Addressables build or other heavy post-build steps if they are not needed for every build.

Step 3: Use build cache if available

Unity Cloud Build and some CI solutions support caching (e.g. Library, packages). Enabling cache can speed up later builds and sometimes reduce peak memory by reusing artifacts.
Ensure cache keys include Unity version and manifest so cache is invalidated when dependencies change.

Verification: If the build completes after increasing resources or enabling cache, document the required timeout and agent size for your team. If it still fails, check the exact error message and Unity/CI logs for the failing step.

Prevention tips

Pin Unity version in Cloud Build and in your repo (e.g. ProjectVersion.txt or CI config) so everyone and CI use the same editor version.
Run a clean local build before pushing to the branch that triggers Cloud Build.
Keep dependencies in manifest and lock file; avoid "works on my machine" packages.
Store secrets in CI/Cloud Build, not in the project.
Monitor build duration; if it grows over time, optimize or add cache to avoid timeouts.