What to Do When Xcode Cloud Fails to Fetch Private Dependencies: 2026 Troubleshooting Guide

A build stops before Xcode starts, and the report mentions a private package or repository.

Fastest fix: Find the failed stage in the build report, then check repository authorization, dependency resolution, or the relevant custom script. A private dependency alone is not a reason to abandon Xcode Cloud; assess a self-hosted Mac only if your network, tools, or control requirements exceed what the workflow can support.

This guide is for engineers maintaining Xcode Cloud workflows who need to trace private repository access failures.
It also helps platform and IT leads responsible for internal Swift packages, Git submodules, or multi-repository builds.
If you are evaluating a different CI environment, use the evidence from a failing build rather than assuming the runner is the cause.

Start with the failed stage, not the error wording

A message such as “repository not found” can point to an access problem, but it does not prove one. A dependency may be unavailable because the repository was never authorized, the resolved revision differs from the committed lockfile, a required tool was not prepared, or a script exited before the build began. Use the report’s stage and surrounding log lines to choose a branch before changing credentials or moving CI.

Apple documents that Xcode Cloud needs access to dependencies and that inaccessible private dependencies or third-party tools can prevent a build from succeeding. That makes access and preparation sensible places to investigate, not automatic diagnoses. Compare the failure location with the steps in Apple’s guide to making dependencies available to Xcode Cloud, then verify the suspected cause in the report or by reproducing the workflow.

Where should you check when Xcode Cloud cannot access a private Swift package? Start with the package’s actual repository host and the connection available to the Xcode Cloud workflow. Then compare the package URL used by the project with the URL and revision recorded for the build. Do not check only the application’s main repository: the dependency may live in a separate private repository.

Verify authorization for every repository the build needs

A workflow can fetch the application source and still fail when it reaches a private Swift package, a Git submodule, or a repository accessed by a script. Make an inventory from the project and build logs. Include repositories used indirectly, not just those listed in the main project settings.

Apple’s code-hosting connection documentation describes connecting source-code management services to Xcode Cloud. If a newly added private dependency fails, the build report may offer a route to request access. Follow that prompt for the service that hosts the dependency, then retry the build and confirm that it passes the same fetch stage.

How do you authorize a private Git submodule? Treat the submodule as a repository with its own access requirement. Check the URL in the .gitmodules file and confirm which code-hosting service and repository it points to. A successful clone of the parent project does not establish that the submodule can also be fetched. If Xcode Cloud presents an access prompt in the failing build report, use it to complete the connection for the submodule’s host.

For organizations with multiple instances of a code-hosting service, distinguish the service from the specific instance. The application and dependency may be on separate instances even if the organization describes them as the same provider. Check which instance the workflow has connected, then inspect the next build report for an authorization prompt if another instance remains unconnected. Apple’s source-code management setup guidance is the reference for this connection flow; it is not a reason to assume that every repository uses the same connection.

An authorization prompt is a clue to follow, not proof that access is the only failure. After completing the connection, confirm that the next build advances beyond the same fetch or resolution stage.

Compare the resolved package state with the committed project

When a package is private but accessible, check whether the build is using the dependency state your team expects. Package.resolved records resolved Swift package versions and revisions. Apple’s continuous integration guidance for Swift packages and apps that use them explains the role of that file in CI workflows. Confirm that the relevant lockfile is committed and located where the project expects it.

What happens if Package.resolved is missing or was not committed? The cloud build may resolve package versions without the exact committed state your developers tested, or it may fail to find the intended private revision. Check the report and the branch’s version-control history before changing resolution settings. Do not make automatic re-resolution the default repair: first establish whether the team intends to use a fixed, reviewed dependency state or deliberately resolve newer compatible versions.

For a useful comparison, reproduce the build from the same commit and workspace context. If local resolution succeeds only because a developer already has cached credentials or package data, that result does not demonstrate that the cloud workflow has the same access. Conversely, if the same revision resolves in a clean environment after repository access is granted, the evidence points toward authorization or workflow setup rather than a package defect.

Check third-party tools and custom script assumptions

A successful source checkout does not guarantee that tools used by the project are ready. If the build relies on CocoaPods, Carthage, or another dependency tool, verify how the workflow installs or invokes it and whether its lockfile is tracked. A developer machine may have a tool installed or configured outside the repository; a cloud build must be able to reproduce the required setup through the project’s workflow and scripts.

Apple’s Xcode Cloud workflow configuration guide covers workflow setup. For custom preparation, Apple documents three named script entry points: ci_post_clone.sh, ci_pre_xcodebuild.sh, and ci_post_xcodebuild.sh. Their names identify when they run in the workflow; see Apple’s custom build script documentation. Use the relevant entry point for the work it is meant to perform rather than putting every operation into an unspecified local setup step.

Check each script’s path, executable state, output, and exit status. Confirm that required files exist at the time the script runs, and make failures visible in the build log. A script that silently assumes an administrator permission, a locally installed binary, or a file outside the checked-out project can behave differently in a managed build environment. Do not treat an unverified privilege assumption as a workaround.

What should you inspect in an Xcode Cloud custom script? Check the script filename and location first, then verify when it runs, which inputs it expects, and whether it exits successfully. If it downloads a tool or repository, confirm that the URL is reachable in the build environment and that its access method is configured for the workflow. Review the output for secrets before sharing logs or adding more diagnostic printing.

Environment variables are another frequent source of mismatches. Compare the variables expected by the script with the values configured for the workflow, and consult Apple’s environment variable reference and Xcode Cloud workflow reference. If a proxy or other network setting is required, verify that it is actually available at the point where the script or dependency tool needs it. Avoid printing credentials or tokens into build output; redact logs before sharing them.

Use this checklist before changing the CI environment

Work through the checks in order. Stop when the build advances past the stage that was failing, then rerun the workflow to verify the repair against the same commit.

• [ ] Identify whether the failure occurs during source checkout, package resolution, a preparation script, or the Xcode build.
• [ ] Record the repository URL shown in the failing log and identify the service or instance that hosts it.
• [ ] Check access separately for the main repository, each private Swift package, each Git submodule, and any repository fetched by a script.
• [ ] Follow an access prompt from the build report if it appears, then retry and confirm the fetch stage completes.
• [ ] Confirm that Package.resolved is committed in the expected project location and matches the intended dependency revision.
• [ ] Verify that third-party tools and their lockfiles are included in a reproducible setup rather than relying on local machine state.
• [ ] Check the relevant custom script’s name, path, execution point, required inputs, and exit status.
• [ ] Validate required environment variables and network settings without exposing secrets in logs.
• [ ] Re-run the affected workflow from the same source revision and compare the new report with the original failure.

Decide whether the workflow needs a different execution environment

If authorization, package state, and script preparation are correct but the build still requires access unavailable to the workflow, document the exact boundary. Examples include an internal repository reachable only through a private network, a required tool or configuration that cannot be prepared in the workflow, or an operational requirement for direct control over the build host. Verify that the requirement is real and reproducible before proposing a migration.

Xcode Cloud avoids the work of operating a separate build host, but you have less direct control over that host. A self-hosted Mac gives your team more control over its environment, but also makes your team responsible for host maintenance, access management, monitoring, and keeping the build setup reproducible. It is not automatically cheaper or more reliable; compare the operational work and requirements your team can verify rather than assuming either outcome.

If you need to assess that route, use a requirements-led comparison of Mac environment options and define how you will test private repository access before making a decision. The key question is not whether a Mac can run the build; it is whether the required network paths, tools, credentials, and controls can be validated in the proposed environment.

When the current workflow fails, moving immediately to a self-hosted Mac can add new failure points: host upkeep, credential handling, and responsibility for keeping tools consistent. On the other hand, repeatedly adjusting a workflow that cannot reach a required private network wastes investigation time. If a verified environment boundary makes managed execution unsuitable and you need a temporary or test build environment, you can review zshmac’s available Mac options and validate your actual access requirements before committing to a longer-term setup. If repository access and workflow preparation solve the failure, staying with Xcode Cloud is the simpler operational choice.