exori

Docs

When a build fails

Bridge classifies build failures rather than handing you the raw log, so most of these have a name you can look up here. Work down the page — the ordering roughly matches the order in which a build hits them.

About 12 minutes

The categories Bridge reports

Every failed build is classified into one of these before you see it. Find yours here first — it tells you which part of the pipeline broke, and the rest of this page covers the ones with specific fixes.

CategoryShown asWhat broke
no_fastlane_configNo Fastlane ConfigBridge never started the build — there is no Fastlane setup to run. See before the build starts.
missing_distribution_credentialsMissing CredentialsAlso pre-flight: the credentials for this platform are incomplete. See before the build starts.
signing_errorSigning / ProvisioningCertificates or provisioning profiles. The big one — see signing failures.
compile_errorCompile ErrorYour source did not build. Nothing to do with Bridge or signing; read the log excerpt and fix the code.
missing_dependencyMissing DependencyA package manager could not resolve something — CocoaPods, SPM, Gradle or npm. Check the excerpt for which.
toolchain_mismatchSDK / Toolchain MismatchThe installed Xcode or SDK version does not match what the project expects. Usually an Xcode upgrade away.
unknownUnclassifiedThe log matched no known pattern. The full log is kept in Build Status — read it there, and tell us, because an unclassified failure is a gap in the classifier.

Before the build even starts

FailureWhat it meansFix
no_fastlane_configNo fastlane/Fastfile with a beta lane where Bridge looks for it.Check Setup → Set Up Fastlane. For a Flutter project the Fastfile belongs in ios/ or android/, not the repo root.
missing_distribution_credentialsThe credentials for this platform are incomplete.iOS needs Issuer ID, Key ID and the .p8 contents. Android needs the service account JSON. Check whether this project has opted into project-specific credentials — an override is never backfilled from the global set.
Tool not found on PATHfastlane, xcodebuild or xcodegen is not where a GUI-launched app can see it.Install via Homebrew, or symlink the binary into /usr/local/bin. Version-manager shims are not on the PATH Bridge inherits.

Signing failures

These are the ones worth reading carefully, because two very different problems produce almost the same message.

  1. Signing "YourApp" requires a development team

    DEVELOPMENT_TEAM is not set in the Xcode project. Add it to project.yml and re-run xcodegen generate, or set the team in Xcode's Signing & Capabilities tab. Setting Team ID in Bridge's Credentials only affects projects scaffolded afterwards.

  2. No profiles for '<bundle id>' were found

    This one has four distinct causes, and they are worth checking in order:

    • No Apple Distribution certificate in your Keychain — security find-identity -v -p codesigning shows only Apple Development. Create one via Xcode → Settings → Accounts → Manage Certificates.
    • The bundle ID is not registered in the developer portal.
    • No App Store Connect app record exists for that bundle ID.
    • build_app is missing xcargs: "-allowProvisioningUpdates", so xcodebuild will not create the profile itself.

  3. Archive succeeds, export fails

    That combination is the signature of a distribution problem specifically: automatic signing can mint a development profile on the fly, so archiving passes on a development certificate alone. The export is where distribution requirements bite.

Upload failures

  1. No value found for 'username' at upload_to_testflight

    The lane is not authenticating with the API key. The generated Fastfile calls app_store_connect_api_key(...) reading ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_CONTENT from the environment Bridge provides. A hand-written or older lane needs that step added.

  2. The build number is already in use

    TestFlight rejects a second upload at the same build number. The generated iOS lane sets it from latest_testflight_build_number + 1; keep that step, or bump it yourself. On Android, versionCode is always yours to manage — Bridge does not touch it.

  3. A Ruby SyntaxError in the Appfile

    If a generated Appfile ended up with a doubled-quoted identifier — app_identifier(""org.cocoapods.…"") — every lane fails outright, not just bundle-ID-dependent ones. That came from a bundle ID mis-detected out of a CocoaPods project file. Fix the Appfile by hand: Bridge refuses to overwrite an existing one, so a repaired file stays repaired.

Bridge is using the wrong bundle ID

Bundle IDs are detected by scanning the project file, and a real project can list several: a test target's, or CocoaPods' org.cocoapods.${PRODUCT_NAME} placeholders. Bridge skips Pods/, Carthage/ and node_modules/ and ignores test-looking identifiers, but detection is best-effort.

If Check Setup shows an identifier you do not recognise, set the Bundle ID field in the Check Setup sheet. That override wins over detection everywhere — the checks, the generated Appfile, and the phone's copy of the checklist.

Pairing and tunnel problems

  1. The QR code expired

    Mint a new one. Codes are short-lived on purpose.

  2. The phone shows the tunnel as not connected

    Check Bridge is actually running — it has no Dock icon, so a quit Bridge is easy to miss. The menu bar item is the tell. Bridge reconnects on a 5-second retry, so a brief network drop recovers on its own.

  3. Nothing recovers it

    Unpair in Bridge and pair again. This clears the stored secrets on both sides and mints a fresh key — cheap, and it rules out a stale pairing.

Git operations fail

Bridge shells out to your system git and relies entirely on your Mac's existing auth — SSH agent or credential helper. If git pull works in Terminal but not in Bridge, the difference is almost always the environment a Finder-launched app inherits.

Still stuck

Open a ticket from the support portal with the failure category and the last dozen lines of the build log. Build history is kept in Bridge's Build Status section, so you can copy it out after the fact.