Skip to content

Troubleshooting

Common Build Issues

Android

Problem: Gradle version mismatch 

# Solution: Use Gradle wrapper
cd common
./gradlew --version
./gradlew clean build

Problem: Dependency resolution failures 

# Solution: Clear Gradle cache
rm -rf ~/.gradle/caches/
./gradlew clean build --refresh-dependencies

iOS

Problem: SPM package resolution fails 

# Solution: Clear SPM cache and re-resolve
./script/build_ios.sh -pP

Problem: Xcode build fails 

# Solution: Clean derived data and rebuild
rm -rf ios/build/DerivedData
./script/build_ios.sh -cb

Problem: Godot version mismatch (headers directory contains the wrong version) 

# The GODOT_VERSION file in the headers directory must match
# the godotVersion property in common/config/godot.properties.
# Solution: remove the existing headers directory and re-download
./script/build_ios.sh -gG

Problem: Build cannot find Godot headers after setting a custom godot.dir 

# Verify the path is set correctly in common/local.properties:
#   godot.dir=/your/custom/path
# Then download the headers into that directory:
./script/build_ios.sh -G

Problem: Build fails with "swift_version not configured" 

# Solution: add swift_version to ios/config/ios.properties, e.g.:
#   swift_version=5.9
# Then retry the build.

Problem: "No such module" errors 

# Solution: Ensure packages are added and resolved
./script/build_ios.sh -pP

Problem: xcodeproj gem missing (Ruby gem required for SPM management) 

# Solution: install the gem manually
gem install xcodeproj --user-install
# The build system will also install it automatically if Ruby is available.

Getting Help