Troubleshooting and FAQ
The messages Build Stream can show you, what each one means, and what to do next. Messages are quoted exactly as the product shows them, with angle brackets for the parts that change, so you can search this page for the text you see.
Connecting a repository
GitHub App
After GitHub sends you back to the Connections page, a line under Connect with GitHub App reports the outcome.
| You see | Why | Do this |
|---|---|---|
| GitHub App installation connected. | The repository was connected. Nothing to fix. | Add a branch. See Branches and build configurations. |
| Choose the GitHub repository to connect. | The app is installed and GitHub returned the list of repositories it can see. | Pick one in Select repository and choose Connect Selected Repository. |
| This environment's GitHub App is not installed on any account you can access. Use Configure GitHub App below to install it. | You chose the already-installed route, but no GitHub account you belong to has the app installed. | Choose Configure GitHub App and install it on the organization that owns the repository. See Configure the app. |
| GitHub App installation failed. | GitHub returned an error state, or the installation was cancelled part way. | Start the connection again. If the same line appears twice, email support with the project name. |
| GitHub App returned to Dev Stream Labs without a repository selection token. Try connecting again. | The return trip lost the one-time token that identifies your installation, usually a page reload or a stale link. | Choose Start over or start the connection again from the card. Do not reuse the URL from the address bar. |
| GitHub returned no repositories for this installation. Confirm the GitHub App was granted access to at least one repository. | The app is installed with access to no repositories, or to repositories you cannot see. | In GitHub, open the organization's installed apps, edit the Dev Stream Labs app and grant it the repository. Then start over. |
| This installation has no repository access. In GitHub, open the app's installation settings and grant it access to at least one repository, then start over. | Same cause as above, shown under an empty repository list. | Grant access in GitHub, then choose Start over. |
| Could not load repositories from this GitHub App installation. | The list request to GitHub failed. Often the token expired while the page sat open. | Choose Start over and connect again without pausing. |
| Could not connect the selected GitHub repository. | The import failed after you picked the repository. The project may already have its one repository. | Check the card count. If it reads 1 / 1 repositories, delete the existing repository first, then connect. |
| GitHub App setup is disabled in this environment. Manual GitHub connection is still available below. | The app route is switched off for this deployment. | Use the token form. See Connect with a token. |
| Could not start GitHub App setup. Manual GitHub connection is still available below. | The install link could not be issued. | Reload the page and try again, or use the token form. |
| Could not disconnect the GitHub App. | The disconnect request failed. | Reload and try again. If it persists, email [email protected]. |
GitHub with a token, Bitbucket Cloud and Diversion
| You see | Why | Do this |
|---|---|---|
| The GitHub personal access token was rejected (invalid or expired). Please generate a new token and try again. | GitHub answered 401 to the token before it was saved. Rate limiting and network failures do not block a save; only a definite rejection does. | Generate a new token with access to the repository and paste it again. A fine-grained token must be granted the repository explicitly. |
| Bitbucket rejected the API token. | Bitbucket answered 401 or 403 to the token when you chose Load repositories. | Check the token and, for an app password or user API token, fill in Username (optional). Leave the username empty for a repository or workspace access token. |
| The credential is valid but has access to no repositories. | Bitbucket accepted the token but listed nothing, often because the workspace is wrong or the token is scoped to a repository you did not name. | Check Workspace against the URL of your repository and give the token read access to it. |
| Could not load repositories from Bitbucket. | The request to Bitbucket failed for a reason other than the token. | Try again in a minute. If Bitbucket is up and it persists, email support. |
| Bitbucket returned HTTP <status>. | Bitbucket answered with an error other than a rejected token. | Check Bitbucket's status page, then try again. |
| Repository Limit Reached / Only one source control repository is allowed per project. | The project already has its one repository. | Choose Delete Repository on the existing card first. See One repository per project. |
| Failed to create server/repository | The save failed and the server gave no more specific reason. | Check every field, then try again. If it persists, email support with the provider and the repository name. |
Pushes do not arrive
The Commits page shows nothing after a push, and no build appears. Work through these in order; the first one that applies is the cause.
- The repository is connected. The card on the Connections page reads 1 / 1 repositories and names your repository.
- The webhook exists at the provider. The GitHub App creates it for you. For every other method you created it from Manage Webhook: on the card, copying Webhook URL and, for GitHub, the Secret. Open the webhook in the provider and compare the URL character by character with the card; the shapes are in the reference.
- The provider delivered it. GitHub and Bitbucket show recent deliveries and the response on the webhook's page. A
200means Build Stream received it; a400with a message from the table below means it was received and refused; no delivery at all means the provider is not sending, which is a provider-side setting (the event type must be push). - The branch is added and confirmed. The pushed branch must appear in Branch Configuration with its row confirmed. A push to any other branch is received and dropped.
- The branch has a build configuration. A branch with nothing in Build Configuration records the commit and creates a build that fails at once; see the build failed.
| You see | Why | Do this |
|---|---|---|
| branch "<branch>" is not configured for repository "<owner/repo>" | GitHub delivered a push to a branch that is not in Branch Configuration. Build Stream answers 200 so GitHub does not retry, and records the notice above. | Add the branch, or push to one that is added. See Pushes to a branch you have not added. |
| no SourceControlServer registered for bitbucket workspace "<workspace>" | A Bitbucket delivery named a workspace that is not the one on the card. | The webhook is on the wrong repository, or Workspace was entered differently from the workspace slug in the repository URL. Reconnect with the slug exactly as Bitbucket writes it. |
| no SourceControlRepository "<repo>" registered for workspace "<workspace>" | The workspace matched but the repository slug did not. | Move the webhook to the repository you connected, or reconnect with the right one. |
| Could not find Source Control Server for <org or project> | A Diversion delivery reached a webhook URL whose organization or project segment does not match this project. The message names whichever segment failed. | Copy Webhook URL from the card again; the last two segments are your organization and project and must not be edited. |
| Could not find Source Control Server for <branch> | A Diversion commit landed on a branch that is not in Branch Configuration. Diversion deliveries on unknown branches are rejected with 400 and not recorded, so no notice appears. | Add the branch first, then commit. See Add the branch before you commit. |
| Not a commit.created event | Diversion sent an event type other than a new commit. Build Stream ignores it with 200. | Nothing. Only commit events start builds. |
| Malformed webhook payload | The body was not the JSON Build Stream expects. Usually the URL was pasted into a service that is not Diversion, or a test ping was sent. | Check which service the webhook belongs to. Real commits deliver correctly formed payloads. |
The build failed before the engine ran
These failures come from Build Stream itself, not from the engine. The job shows Build failed within seconds, the Build Steps panel is empty, and the message is the first thing in the log's Setup · stderr stream, prefixed OVERALL WORKER PROCESS ERROR:. The same text is the second line of a Slack or Discord failure notification.
| You see | Why | Do this |
|---|---|---|
| No autobuild configurations found for branch "<branch>". Configure at least one build configuration before submitting this branch to the Build Controller. | The branch is on On Every Commit and a push arrived while its Build Configuration cell was empty. A failed build is created so the push is not silently lost. | Open the branch row and select at least one configuration. Later pushes build; this one does not retry. Push again, or delete the failed build and use Build Now if the branch is scheduled. |
| This repository has no build toolchain configured: the environment's PROJECT_TOOLCHAIN / PROJECT_TOOLCHAIN_VERSION / PROJECT_LICENSE_TYPE settings are empty. Configure the project settings and re-run the build. | The project was created without a toolchain, or the setting did not reach the Build Stream service. | In the Home app, edit the project and set Toolchain and Toolchain Version. Wait for the service to restart, then push again. See Choose the toolchain. |
| This repository has toolchain '<toolchain>' but no toolchain version configured: the environment's PROJECT_TOOLCHAIN_VERSION setting is empty. Configure the project settings and re-run the build. | The toolchain is set but its version is not, so no build machine can be matched. | Set Toolchain Version in the project settings and push again. |
| This project is configured for <toolchain> <major.minor>, but the repository is authored with <version>. Update the toolchain version in project settings to match the project, then re-run the build. | Build Stream read the engine version from the repository (for Unity, ProjectVersion.txt) and its major.minor differs from the project setting. Neither can be right, so it stops rather than build with the wrong engine. | Change Toolchain Version in the project settings to the stream the repository uses, then push again. A patch-level difference within the same stream does not trigger this; the discovered version is used. |
| Waiting for available Unity product license type=<type> | Not a failure. Every licence of the project's type is in use by another build. The job waits and takes the next free one. | Wait. If it waits longer than your builds usually take, another project may be holding licences; email support. |
| No Unity product license configured for license_type=<type> | The project's License Type is Industrial or Professional but no licence of that type is registered for your organization. | Either change License Type in the project settings to one you hold, or email [email protected] to register your licence. Personal/Indie needs no registered licence. |
| Build profile '<name>' is selected for this branch but no longer exists in the repository (it may have been deleted or renamed). Update the branch's build configurations and re-run the build. | A Unity build profile chosen in Build Configuration was removed or renamed in the repository since it was selected. | Open the branch row, deselect the missing profile and select its replacement, then push again. See Unity build profiles. |
| [Controller unreachable] strike=<n> url=<url> | Written to the Setup · stdout stream while the job is still Build in progress...: Build Stream cannot reach the build controller. The job is not failed; it retries on every pass. | Wait. The farm is restarting or updating. If the strike count keeps rising for more than a few minutes, check the status page and email support. |
| Gave up submitting this build to the Build Controller after <n> attempts. The Build Controller never acknowledged the job. | The controller accepted connections but never acknowledged the job across about two hours of retries. | Push again once the status page is clear, and email [email protected] with the build number; this one is on our side. |
| Missing branch reference / Missing push reference / Missing repository reference / Missing source control server reference | The branch or repository the build belonged to was deleted and recreated while the job was queued, so the job no longer points at anything. | Delete the failed build and push again. The new push builds against the recreated branch. |
| submit_build_job_to_controller crashed | Shown as the job's status while it is retried. The usual cause is that Build Stream could not fetch the repository: an expired token, a repository the App can no longer see, or the App uninstalled. | Check the repository card. For a token connection, edit the card and paste a fresh token; for the GitHub App, confirm the app is still installed and has the repository. See Connecting a repository. |
Build Now was refused
| You see | Why | Do this |
|---|---|---|
| Build already exists for this commit | The commit has a build that is not in the trash. | Open it on the Builds page. To rebuild, delete every build of the commit first. |
| No build configurations found for this branch | The commit's branch has nothing selected in Build Configuration. | Select at least one configuration on the branch row, then choose Build Now again. |
| Commit has no associated branch | The branch the commit arrived on has since been deleted. | Add the branch again and push a new commit. |
Farm availability warnings
The configuration picker on a branch row asks the build farm what it can build for your toolchain right now and annotates any platform it cannot. The warning names the missing thing so you can tell a temporary gap from a permanent one. You can still select the platform; a job for it waits as Waiting for a build machine until a machine can take it.
| You see | Why | Do this |
|---|---|---|
| No <Platform> builder has Unity 6000.1.5f1 installed | A machine for that operating system exists but does not have your toolchain version. | Wait for the install, or change the project's Toolchain Version to one the farm has; the picker lists the versions it knows about. Email support if you need this version added. |
| No <Platform> builder has the required toolchain installed | The same, when the toolchain version could not be named. | As above. |
| No <Platform> builder on the farm | No machine of the operating system that platform needs is registered at all. | Email [email protected] with the platform and toolchain. macOS and iOS need a Mac. |
| A <Platform> builder is installing Unity 6000.1.5f1 | A machine is provisioning your toolchain version now. | Wait. Reopen the picker to refresh; the warning clears when the install finishes. |
| A <Platform> builder is installing the required toolchain | The same, when the version could not be named. | Wait and reopen the picker. |
| The <Platform> builder is offline | The only machine that can build this platform is not connected. | Wait; machines reconnect on their own after an update. Jobs queue rather than fail. If it stays offline for an hour, email support. |
| <Toolchain> cannot build <Platform> | Not a farm gap: this engine has no such target in any release, so no machine or install will change it. | Deselect the platform. The row is greyed out for this reason. |
| Coming soon | Shown on the Switch, Xbox and PlayStation rows. Console builds are not offered yet. | Nothing to do; the rows cannot be selected. |
Availability is fetched when the page loads and again whenever you open the picker, so a machine that came online a minute ago clears its warning without a page reload.
Frequently asked questions
Can a project have more than one repository?
Not today. The Connections page shows the count as 0 / 1 or 1 / 1 repositories, and Add is disabled once one exists; trying again shows Repository Limit Reached. To switch repositories, delete the existing one from its card and add the new one.
How long is a deleted build kept?
Currently 24 hours. Deleting moves the build to Deleted Builds with a countdown; Restore puts it back at any point before the countdown ends. After that the build and its artifact are removed from storage and cannot be recovered.
Are old builds deleted automatically?
Yes. Builds older than the retention window, 90 days unless the platform sets a different one, are moved to Deleted Builds by a scheduled sweep and follow the same 24-hour countdown, so you can still restore one you need for a day after it is swept.
What time zone is a nightly or weekly build time in?
Yours. The label next to the time picker names the zone of the browser you are using, for example Time (PDT):. The time is stored in UTC, so two people in different zones see the same moment written differently. Next build: under the picker shows when it fires next, also in your zone.
Can I build a commit without pushing again?
Only on a branch scheduled Nightly Only or Weekly Only, and only for a commit that has no builds yet: open the commit on the Commits page and choose Build Now. On an On Every Commit branch every push already builds, so the button never appears. To rebuild a commit that has been built, delete its builds first; trashed builds do not count.
Why is there no Download button on a failed build?
Download appears only on a job whose status is Build succeeded and which produced an artifact. A failed or canceled job produced none. Open View Log to see what happened; the viewer jumps to the first error.
Where do my keystore, certificates and passwords go?
They are stored encrypted as secrets on the branch and used by the build machine when it builds that branch. They are never sent back to the browser, which is why the signing form comes back blank after a reload; only the iOS Signing style is shown again.
How do I change the toolchain version Build Stream builds with?
In the project's settings in the Home app: open the project, choose Edit Project and change Toolchain Version. The Connections page shows the version but does not edit it; the link there opens the Home app. A version edit restarts the Build Stream service for about a minute and a half.
Can I use both the GitHub App and a personal access token?
Not for the same project, because a project has one repository. Pick one: the GitHub App if you can install it on the organization, the token form if you cannot. Disconnecting the app or deleting the repository frees the slot for the other method.
A push built the wrong commit. Why?
A build is created for the head commit of a push. If you pushed several commits at once, only the last one is built. Push commits separately when each one needs its own build.
Does Build Stream verify that a webhook delivery really came from my provider?
GitHub deliveries are verified against the shared secret shown on the card. Bitbucket and Diversion deliveries are accepted without a signature check today, so treat those webhook URLs as private.
Reference
Build schedules
| Option | When it builds | Extra fields |
|---|---|---|
| On Every Commit | On every push to the branch, the head commit of the push. | None. This is the default for a new branch. |
| Nightly Only | Once a day, the latest push on the branch, unless it has already been built. | Time (<zone>): picked from a list in your zone. Next build: shows the next run. |
| Weekly Only | Once a week, the latest push on the branch, unless it has already been built. | The time, plus Day: from Monday to Sunday. |
Build configuration names
A configuration is written <platform>-<flavor>. The picker groups them by platform under its display name and shows the flavors as toggles; the wire name is what appears on job rows, artifact names and notifications.
| Platform (display name) | Configurations |
|---|---|
| win32 (Windows) | win32-debug · win32-release · win32-shipping |
| macos (macOS) | macos-debug · macos-release · macos-shipping |
| ios (iOS) | ios-debug · ios-release · ios-shipping |
| android (Android) | android-debug · android-release · android-shipping |
| linux (Linux) | linux-debug · linux-release · linux-shipping |
| webgl (WebGL) | webgl-debug · webgl-release · webgl-shipping |
| switch, xbox, playstation | Listed with a Coming soon tag; not selectable today. |
Unity projects can also select build profiles found in the repository; those keep the profile's own name. See Unity build profiles.
Webhook URLs
| Provider | Shape | Example |
|---|---|---|
| GitHub (App or token) | https://buildstream.<project>.<org>.…/api/build-stream/webhooks/github/ | https://buildstream.starfall.northwind.example.com/api/build-stream/webhooks/github/ |
| Bitbucket Cloud | https://buildstream.<project>.<org>.…/api/build-stream/webhooks/bitbucket/ | https://buildstream.starfall.northwind.example.com/api/build-stream/webhooks/bitbucket/ |
| Diversion | https://buildstream.<project>.<org>.…/api/build-stream/webhooks/dv/<org>/<project>/ | https://buildstream.starfall.northwind.example.com/api/build-stream/webhooks/dv/northwind/starfall/ |
| Perforce | No URL to paste. A hosted server is connected by the Build on check-in switch. | Build on check-in |
Copy the URL from Webhook URL on the card rather than typing it. GitHub deliveries are signed with the card's Secret; Bitbucket and Diversion deliveries are not signature-checked today.
Retention and limits
| What | Value |
|---|---|
| Repositories per project | 1 |
| Deleted build kept in Deleted Builds before permanent removal | 24 hours |
| Age after which a build is moved to Deleted Builds automatically | 90 days by default |
| Builds created per push | 1, with one job per selected configuration |
| Artifacts per job | 1 zip, named after the configuration |
| Submit retries before a build is given up | 10 attempts over about two hours |
Getting help
Something out of date or unclear? Email [email protected].