Build Failures

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

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