Build Failures

Note

Error messages shown below are illustrative. Real errors will use the format SSH command failed (exit N): <stderr> or similar from the agent.

Step Command Failed

Error:

Command failed with exit code 1

or

Non-zero exit status

Cause: The step command executed and returned a non-zero exit code, indicating failure.

Common reasons:

• Dependency installation failed
• Missing tools or libraries
• Incorrect script paths or working directory
• Build compilation errors
• Test failures

Solution:

1. Check the step logs in the RunnerHub dashboard
2. Identify which command failed (look for error output in logs)
3. Review the error message for details
4. Common fixes:
   • Ensure all dependencies are installed first
   • Verify file paths are correct and relative to repo root
   • Check that tools are available (xcodebuild, fastlane, etc.)

Example fix:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Install dependencies
    run: pod install

  - name: Build
    run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build

CocoaPods Installation Failure

Error:

pod install failed
Error installing pods

Cause: Common CocoaPods issues:

• Outdated or stale pod repository
• Incompatible pod versions
• Missing or corrupted lockfile
• Network issues fetching specs

Solution:

Try updating the pod repository before installing:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Install pods
    run: |
      pod repo update
      pod install

Or if you're debugging:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Update pods
    run: pod repo update

  - name: Install pods
    run: pod install

Tip

pod repo update refreshes the CocoaPods spec repository from the internet. This can take time but resolves most pod-related issues.

If the problem persists:

• Check your Podfile for syntax errors
• Verify all pods are compatible with your iOS version
• Update your pods: pod update (updates to latest compatible versions)

Xcode Build Failure

Error:

xcodebuild exited with code 65

or other non-zero exit codes

Cause: Typical Xcode build issues:

• Incorrect scheme name
• Missing workspace or project
• Incompatible SDK settings
• Build settings misconfiguration
• Derived data corruption

Solution:

1. Verify scheme exists:

   xcodebuild -workspace MyApp.xcworkspace -list

   This lists all available schemes. Ensure your scheme is spelled correctly.

2. Verify workspace path:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Build
       run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build

   If you don't have a .xcworkspace, use -project instead:

   xcodebuild -project MyApp.xcodeproj -scheme MyApp build

3. Check destination: For iOS testing, specify the simulator:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Test
       run: |
         xcodebuild \
           -workspace MyApp.xcworkspace \
           -scheme MyApp \
           -destination 'platform=iOS Simulator,name=iPhone 15' \
           test

4. Clean if cache is corrupted:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Clean build
       run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp clean build

Timeout Exceeded

Error:

Job exceeded maximum execution time

Cause: Your job took longer than the configured timeout value.

Solution:

1. Increase the timeout in your runnerhub.yml:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   timeout: 60  # 60 minutes

2. Maximum timeout depends on your plan:

   | Plan | Max Timeout | |------|------------| | Free | 30 minutes | | PAYG | 60 minutes | | Pro | 90 minutes | | Business | 120 minutes |

3. To use timeouts longer than your plan allows, upgrade to a higher plan:

   • Go to Billing
   • Click Upgrade Plan

4. Alternatively, optimize your build to run faster:

   • Enable caching for dependencies
   • Run tests in parallel
   • Skip unnecessary steps for certain branches

Script Not Found

Error:

sh: script.sh: No such file or directory

or

Error: script not found

Cause: The script referenced in your pipeline doesn't exist or is in a different directory.

Solution:

1. Ensure the script is committed to your repository

2. Use the correct relative path from the repo root:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Run script
       run: sh scripts/build.sh

3. Verify the file exists by checking:

   • Is it in .gitignore? (It won't be checked out)
   • Is the path relative to repo root correct?
   • Is the filename spelled correctly (case-sensitive on Mac/Linux)?

Permission Denied

Error:

Permission denied

Cause: The script doesn't have execute permissions.

Solution:

1. Add execute permissions to the script:

   chmod +x scripts/build.sh

2. Commit the permission change:

   git add scripts/build.sh
   git commit -m "Make build script executable"

Alternatively, run it via shell explicitly:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Run script
    run: sh scripts/build.sh  # 'sh' doesn't require execute bit

Environment Variables Not Available

Error:

$API_TOKEN is empty

or

Undefined variable: SECRET_KEY

Cause: The environment variable is not defined. Environment variables are scoped per app and must be explicitly configured.

Solution:

1. Go to App > Environment tab in the dashboard

2. Add your variable:

   • Name: API_TOKEN (or your variable name; must match ^[A-Z0-9_]+$)
   • Value: Your secret value

3. Click Add Variable

4. Use it in your pipeline:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Deploy
       run: fastlane deploy
       env:
         API_TOKEN: $API_TOKEN

Caution

Environment variables are:

• Scoped per app (app-level overrides workspace-level)
• Encrypted at rest and masked in logs (never displayed as plain text)
• Cannot be displayed again after you save them
• Only available at runtime (not during YAML parsing)

Verify the secret name matches your variable reference (case-sensitive).

Missing Dependencies

Error:

command not found: xcodebuild

or

No such file or directory: /usr/bin/fastlane

Cause: Required tools are not installed in the build environment.

Solution:

1. For Xcode tools (xcodebuild, swift, etc.):

   • These are pre-installed on the RunnerHub macOS build system
   • If missing, verify you're using the correct command name

2. For CocoaPods (pod):

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Install pods
       run: |
         gem install cocoapods
         pod install

3. For Fastlane:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Install Fastlane
       run: |
         gem install fastlane
         fastlane build

4. For other Ruby gems:

   name: Pipeline
   platform: ios
   
   environment:
     xcode: "16.4"
   
   steps:
     - name: Install gems
       run: |
         bundle install
         bundle exec fastlane build

Git Authentication Failure in a Step (Submodules, LFS, Fetch)

Error:

fatal: could not read Username for 'https://github.com': terminal prompts disabled

or

fatal: Authentication failed for 'https://github.com/your-org/your-private-repo.git/'

Typically raised by one of:

git submodule update --init --recursive
git lfs pull
git fetch --tags

Cause: After cloning and checking out your repository, RunnerHub removes the authenticated remote URL from .git/config before your first step runs. It rewrites origin to the plain URL, so the clone credential is no longer stored on disk during your build.

This is deliberate. The credential previously stayed in .git/config for the whole job, where two accidents could leak it somewhere that outlives the VM:

• a broad artifacts: glob (**/*, .) zips .git/config and uploads a live token to the artifact store;
• an ordinary git remote -v or git config --list in a step prints it into the build log.

The checkout itself is unaffected — your code is already on disk. Only steps that reach back out to the remote are affected, and only on private repositories:

| Operation | Private repo | Public repo | |-----------|--------------|-------------| | git submodule update --init with relative URLs | Fails | Works | | git lfs pull / git lfs fetch | Fails | Works | | git fetch / git pull for extra branches or tags | Fails | Works | | Building code already checked out | Works | Works |

Relative submodule URLs (../shared-lib.git in .gitmodules) are resolved by git against the parent remote, which is exactly what no longer carries a credential.

Caution

git-lfs is installed in the golden image, so git lfs runs — but against a private remote it is now unauthenticated. A present binary does not imply an authenticated remote.

Solution:

RunnerHub has no built-in submodule or Git LFS authentication. There is no submodules:, lfs:, or checkout: key in the pipeline YAML schema, and the platform does not expose the clone credential to your steps. This is a current limitation.

To reach a private remote from a step you must supply your own token as a workspace environment variable and authenticate with it explicitly.

1. Create a token with read access to the repositories you need (a GitHub fine-grained PAT, a GitLab project access token, or a Bitbucket app password).
2. Add it as an environment variable on your app in the dashboard — mark it as a secret so it is masked in logs. This example calls it GIT_TOKEN.
3. Write it to $HOME/.netrc before the git operation:

name: Build with Submodules
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Authenticate git
    run: |
      echo "machine github.com login x-access-token password $GIT_TOKEN" > $HOME/.netrc
      chmod 600 $HOME/.netrc

  - name: Fetch submodules
    run: |
      cd $RUNNERHUB_CLONE_DIR
      git submodule update --init --recursive

  - name: Build
    run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build

Use the login value that matches your provider:

| Provider | machine | login | |----------|-----------|---------| | GitHub | github.com | x-access-token | | GitLab | gitlab.com | oauth2 | | Bitbucket | bitbucket.org | x-token-auth |

The same .netrc authenticates git lfs pull and git fetch.

Caution

Write the token to $HOME/.netrc, not back into the repository.

$HOME (/Users/<user>) sits outside $RUNNERHUB_CLONE_DIR (/Users/<user>/workspace/repo), so .netrc is not picked up by workspace-relative artifacts: globs, and no cache type archives it (every cache path names a specific subdirectory such as ~/.gem or ~/.gradle/caches).

Do not "simplify" this to git remote set-url origin https://x-access-token:$GIT_TOKEN@github.com/.... That writes your token straight back into .git/config and re-creates the exact leak the platform just closed.

Note

git -c name=value ... and git --config=... are rejected by the agent's command validator, so the usual git -c url."...".insteadOf=... one-liner will not run. Use .netrc instead.

Artifacts Not Uploaded

Error: Artifacts are not visible in the dashboard after a successful build.

Cause: Possible reasons:

1. Artifact path pattern doesn't match any files
2. Your plan doesn't include persistent artifacts

Solution:

1. Verify artifact path exists:

   artifacts:
     - build/**/*.ipa

   Ensure the path glob matches your actual output files.

2. Check artifact retention by plan:

   | Plan | Artifact Retention | |------|------------------| | Free | Deleted after job cleanup | | PAYG | 7 days | | Pro | 30 days | | Business | 90 days |

3. If you're on the Free plan:

   • Configure your own artifact storage (e.g., upload to S3, TestFlight, GitHub releases)
   • Example with Fastlane uploading to TestFlight:

     name: Pipeline
     platform: ios
     
     environment:
       xcode: "16.4"
     
     steps:
       - name: Build and upload
         run: fastlane build

Build Cache Issues

Symptom: Cache is not being restored on subsequent builds, or a build fails due to stale cache.

Cause:

• Lock file changed (e.g., Podfile.lock, Package.resolved) → cache key changed → cache miss
• Cache was manually cleared
• Cache is older than 14 days

Solution:

1. Force cache refresh:

   • Commit a new pod install or swift package resolve
   • This regenerates the cache key with updated lock files

2. Clear cache manually:

   • Go to App > Settings
   • Click Clear Cache
   • Run your build again

3. Monitor cache size:

   • Cache is limited to 50GB per agent
   • If exceeded, oldest entries are evicted
   • Reduce cache size by removing unnecessary dependencies

Tip

Cache misses never fail builds. If cache restore fails, the build continues without cache.

See Cache Problems for more details.

Quick Debugging

Create a debug pipeline to identify issues:

name: Debug Pipeline
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Print environment
    run: env

  - name: Show working directory
    run: pwd

  - name: List files
    run: ls -la

  - name: List schemes
    run: xcodebuild -workspace MyApp.xcworkspace -list

  - name: Show Xcode version
    run: xcodebuild -version

This helps identify:

• Missing files
• Incorrect working directory
• Environment configuration issues
• Available schemes and SDKs