Skip to main content
This guide covers common issues you might encounter with fastlane and how to resolve them.

​
Quick Diagnostics

​
Check Your Environment

First, gather diagnostic information: 
fastlane env
This command generates a comprehensive report including:
  • fastlane version
  • Ruby version
  • Xcode version (macOS)
  • Operating system
  • Installed plugins
  • Environment variables
Always include the output of fastlane env when reporting issues on GitHub.

​
Enable Verbose Logging

Run commands with verbose output to see detailed information: 
fastlane beta --verbose
Or set the environment variable: 
VERBOSE=1 fastlane beta

​
Check fastlane Status

Verify fastlane and dependencies are up to date: 
# Check current version
fastlane --version

# Update fastlane
bundle update fastlane

# Update plugins
fastlane update_plugins

​
Common Issues

​
Problem

Invalid username and password combination
Could not authenticate with Apple

​
Solutions

1. Two-Factor Authentication (2FA)If you have 2FA enabled, use one of these methods:Option A: Use App Store Connect API (Recommended)
lane :beta do
  app_store_connect_api_key(
    key_id: "ABC123",
    issuer_id: "xxx-xxx-xxx",
    key_filepath: "./AuthKey_ABC123.p8"
  )
  pilot
end
Option B: Use FASTLANE_SESSIONGenerate a session:
fastlane spaceauth -u [email protected]
Copy the output and set it as environment variable:
export FASTLANE_SESSION='---\n- !ruby/object:HTTP::Cookie...'
Option C: Use Application-Specific Password
  1. Generate at appleid.apple.com
  2. Set environment variable:
FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD=abcd-efgh-ijkl-mnop
2. Session ExpiredRegenerate your session:
fastlane spaceauth -u [email protected]
3. Wrong Team SelectedSpecify team explicitly:
FASTLANE_TEAM_ID=ABC123XYZ fastlane beta

​
Problem

No signing certificate found
Provisioning profile doesn't match
Code signing error

​
Solutions

1. Use match (Recommended)
lane :beta do
  match(type: "appstore", readonly: true)
  gym
end
If certificates are missing:
# Generate new certificates (run once, not on CI)
fastlane match appstore
2. Check Certificate ValidityVerify certificates haven’t expired:
  • Open Keychain Access
  • Check certificate expiration dates
  • Regenerate if expired: fastlane match nuke distribution
3. Clean Build
# Clean Xcode derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Clean project
xcodebuild clean
4. Reset Codesigning
lane :beta do
  update_code_signing_settings(
    use_automatic_signing: false,
    path: "MyApp.xcodeproj"
  )
  match(type: "appstore")
  gym
end
5. Check Bundle IdentifierEnsure your app’s bundle identifier matches the provisioning profile:
update_app_identifier(
  xcodeproj: "MyApp.xcodeproj",
  plist_path: "MyApp/Info.plist",
  app_identifier: "com.example.app"
)

​
Problem

Error building the application
gym failed with error
xcodebuild failed

​
Solutions

1. Check Scheme and Configuration
gym(
  scheme: "MyApp",
  configuration: "Release",
  export_method: "app-store"
)
2. Verify Xcode Version
xcode-select --print-path
xcodebuild -version
Switch Xcode version if needed:
sudo xcode-select --switch /Applications/Xcode.app
3. Clean and Rebuild
lane :beta do
  clean_build_artifacts
  clear_derived_data
  gym
end
4. Check Build LogsLook at detailed build logs:
fastlane gym --verbose
Logs are saved to:
~/Library/Logs/gym/
5. Dependency Issues
# CocoaPods
bundle exec pod install --repo-update

# Carthage
carthage update --platform iOS

# SPM
xcodebuild -resolvePackageDependencies

​
Problem

Failed to upload to App Store Connect
Could not upload IPA
Timeout waiting for build processing

​
Solutions

1. Check IPA FileVerify the IPA was built successfully:
ls -lh *.ipa
2. Use App Store Connect API
lane :beta do
  app_store_connect_api_key(
    key_id: ENV["ASC_KEY_ID"],
    issuer_id: ENV["ASC_ISSUER_ID"],
    key_filepath: "./AuthKey.p8"
  )
  
  pilot(
    skip_waiting_for_build_processing: true
  )
end
3. Increase Timeout
pilot(
  wait_for_uploaded_build: true,
  wait_processing_timeout_duration: 1800  # 30 minutes
)
4. Manual UploadIf automated upload fails, use Transporter:
xcrun altool --upload-app -f app.ipa \
  -u [email protected] \
  -p @keychain:AC_PASSWORD
5. Check App Store Connect StatusVerify App Store Connect is operational:If there’s an outage, wait and retry later.

​
Problem

Plugin not found
Action not available
Gem dependency conflicts

​
Solutions

1. Install Dependencies
bundle install
2. Check PluginfileVerify fastlane/Pluginfile exists and lists your plugins:
gem 'fastlane-plugin-versioning'
gem 'fastlane-plugin-firebase_app_distribution'
3. Update Plugins
fastlane update_plugins
4. Run with Bundle ExecAlways use bundle exec to ensure correct versions:
bundle exec fastlane beta
5. Clear Bundler Cache
bundle clean --force
bundle install
6. Check Plugin InstallationVerify plugin is loaded:
bundle exec fastlane lanes --verbose
You should see a plugins table listing installed plugins.

​
Problem

Parameter missing
Configuration not found
Environment variable not set

​
Solutions

1. Check .env FilesVerify .env file exists and contains required variables:
cat fastlane/.env
2. Verify File Location.env files should be in:
  • fastlane/.env (preferred)
  • ../.env (project root)
3. Load Specific Environment
fastlane beta --env production
4. Check Variable NamesEnsure correct environment variable names:
# List all fastlane-related variables
env | grep FASTLANE
env | grep FL_
5. Quote Values with SpacesIn .env files:
APP_NAME="My App Name"
NOT_THIS=My App Name  # This won't work

​
Problem

Permission denied
Operation not permitted
Access denied

​
Solutions

1. Keychain AccessUnlock keychain before running:
lane :beta do
  unlock_keychain(
    path: "login.keychain",
    password: ENV["KEYCHAIN_PASSWORD"]
  )
  match
  gym
end
2. File Permissions
chmod +x fastlane/Fastfile
chmod 600 .env  # Secure permissions for credentials
3. CI KeychainCreate temporary keychain on CI:
lane :beta do
  create_keychain(
    name: "temp.keychain",
    password: ENV["KEYCHAIN_PASSWORD"],
    default_keychain: true,
    unlock: true,
    timeout: 3600,
    lock_when_sleeps: false
  )
  
  match(
    keychain_name: "temp.keychain",
    keychain_password: ENV["KEYCHAIN_PASSWORD"]
  )
end

​
Problem

Gem version mismatch
Bundler version conflict
Ruby version too old

​
Solutions

1. Check Ruby Version
ruby --version
fastlane requires Ruby 2.5 or later. Update if needed:
# Using rbenv
rbenv install 3.1.0
rbenv global 3.1.0

# Using rvm
rvm install 3.1.0
rvm use 3.1.0 --default
2. Update Bundler
gem install bundler
bundle update --bundler
3. Clean Gemfile.lock
rm Gemfile.lock
bundle install
4. Use Specific VersionsPin versions in Gemfile:
source "https://rubygems.org"

gem "fastlane", "~> 2.200.0"

​
Debugging Techniques

​
Add Breakpoints with pry

Add to your Fastfile for interactive debugging: 
lane :debug do
  require 'pry'
  
  result = gym
  binding.pry  # Execution pauses here
  
  pilot
end
Run with: 
bundle exec fastlane debug

​
Inspect Lane Context

Check shared values between actions: 
lane :debug do
  gym
  
  # Print all shared values
  puts Actions.lane_context.keys
  puts Actions.lane_context[SharedValues::IPA_OUTPUT_PATH]
  
  pilot
end

​
Dry Run Mode

Create a dry run option to test without side effects: 
lane :deploy do |options|
  if options[:dry_run]
    UI.important("🔍 DRY RUN MODE - No uploads will be performed")
  end
  
  gym
  
  unless options[:dry_run]
    pilot
  end
end
Run with: 
fastlane deploy dry_run:true

​
Debug HTTP Requests (Spaceship)

Enable debug mode for Apple API calls: 
SPACESHIP_DEBUG=1 fastlane beta
Use with Charles Proxy or mitmproxy: 
SPACESHIP_DEBUG=1 SPACESHIP_PROXY=http://localhost:8888 fastlane beta

​
Test Actions Individually

Test single actions using fastlane run: 
fastlane run pilot username:[email protected] skip_submission:true

​
Check Action Documentation

View detailed action documentation: 
fastlane action gym
fastlane action pilot
fastlane action match

​
Getting Help

​
Search Existing Issues

Before creating a new issue:
  1. Search GitHub Issues
  2. Check docs.fastlane.tools
  3. Look for similar problems on Stack Overflow

​
Report a Bug

When reporting issues on GitHub:
  1. Run diagnostic command:
fastlane env > fastlane-env.txt
  1. Capture full output:
fastlane beta --verbose --capture_output 2>&1 | tee output.txt
  1. Include in issue:
    • Clear description of the problem
    • Expected vs actual behavior
    • Steps to reproduce
    • Output from fastlane env
    • Full error output
    • Relevant Fastfile content
Before sharing output, remove sensitive information like:
  • API keys
  • Passwords
  • Team IDs
  • Bundle identifiers (if private)

​
Community Support

  • GitHub Discussions: Ask questions and share tips
  • Stack Overflow: Tag questions with fastlane
  • Twitter: Follow @FastlaneTools

​
Prevention Tips

​
Use Version Control

Commit your fastlane configuration: 
git add Fastfile Gemfile Gemfile.lock Pluginfile
git commit -m "Update fastlane configuration"

​
Pin Dependencies

Avoid surprises with specific versions: 
# Gemfile
gem "fastlane", "~> 2.200.0"  # Minor updates only

​
Regular Updates

Keep fastlane updated, but test changes: 
# Update in development first
bundle update fastlane
fastlane test

# Then commit and deploy to CI
git add Gemfile.lock
git commit -m "Update fastlane to 2.200.0"

​
CI Best Practices

  • Lock keychain access
  • Use readonly match mode
  • Set appropriate timeouts
  • Clean workspace between builds
  • Cache dependencies when possible

​
Monitoring

Set up notifications for failures: 
error do |lane, exception|
  slack(
    message: "Lane #{lane} failed!",
    success: false,
    payload: {
      "Error" => exception.message
    }
  )
end
Run fastlane lanes to see all available lanes and their descriptions. Add the --verbose flag to see loaded plugins and configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us