Troubleshooting

Platform note

All iOS-related sections below (CocoaPods, Xcode, Ruby/rbenv, the fmt workaround) apply to macOS only — building and running the iOS app requires a Mac with Xcode. The Android and JavaScript sections apply to macOS, Linux, and Windows alike.

Commands using brew rely on Homebrew, the macOS package manager. If you do not have it, install it first.

Native module not found

Error:

TrainingKitModule is not available

The native module was not registered. Reinstall native dependencies and rebuild the app — a Metro reload is not sufficient after adding a native package:

yarn install
cd ios
pod install
cd ..
yarn ios

iOS: pod install hangs or fails

React Native iOS builds are sensitive to Ruby and CocoaPods versions. If pod install hangs, check which Ruby is active:

ruby --version
which ruby
bundle --version
which bundle

If Ruby 4 is selected, switch to Ruby 3.x with rbenv:

brew install rbenv ruby-build
rbenv install 3.3.6
rbenv local 3.3.6
eval "$(rbenv init -)"
gem install bundler
bundle install

Then run pods through Bundler:

cd ios
bundle exec pod install

If your shell does not pick up the rbenv Ruby after restarting the terminal, add the following line to your shell configuration file, then restart the terminal. On macOS the default shell is Zsh, so the file is ~/.zshrc (use ~/.bash_profile if you use Bash):

eval "$(rbenv init -)"

iOS: component missing in Xcode

Error:

iOS 26.x is not installed. Please download and install the platform from Xcode > Settings > Components.

Open Xcode, go to Settings → Components, and install the matching iOS platform. Then run:

yarn ios

iOS: fmt consteval build error

Error:

call to consteval function ... is not a constant expression

This occurs with recent Xcode/iOS SDK combinations against React Native's fmt pod. Add a post_install hook in ios/Podfile. If your Podfile already has a post_install do |installer| block, merge the body below into it instead of adding a second block:

post_install do |installer|
  fmt_base_header = File.join(installer.sandbox.root, 'fmt/include/fmt/base.h')
  if File.exist?(fmt_base_header)
    File.chmod(0644, fmt_base_header)
    contents = File.read(fmt_base_header)
    contents = contents.gsub('#elif defined(__cpp_consteval)', '#elif 0 && defined(__cpp_consteval)')
    contents = contents.gsub('#elif FMT_GCC_VERSION >= 1002 || FMT_CLANG_VERSION >= 1101', '#elif 0 && (FMT_GCC_VERSION >= 1002 || FMT_CLANG_VERSION >= 1101)')
    File.write(fmt_base_header, contents)
  end
end

Run pod install again after adding the workaround.

iOS: TrainingKit.xcframework missing

Error:

ios/Vendor/TrainingKit.xcframework not found

The framework was not fetched during pod install. Fetch it manually and reinstall pods:

yarn fetch:ios-trainingkit
cd ios
pod install

Android: cannot resolve com.fysiki:trainingkit

Error:

Could not resolve com.fysiki:trainingkit:vX

The GitHub Packages Maven repository is either not configured or credentials are missing.

1. Verify that the maven { url "https://maven.pkg.github.com/getfizzup/trainingkit-android-sdk" ... } block is present in both buildscript and allprojects in android/build.gradle.
2. Check that credentials are available in android/local.properties or as GITHUB_USERNAME and GITHUB_TOKEN environment variables.

See Installation – Android setup for the full configuration.

Duplicate native module or duplicate Activity

If you previously copied bridge files into the host app, remove them after installing the package. Keeping both produces duplicate module registrations or duplicate Android manifest entries. See Installation for the full list of files to remove.

Local file dependency does not update

When using a local file dependency:

"trainingkit-reactnative": "file:../relative/path/to/trainingkit-reactnative"

Changes to the package are not reflected until you re-run the install and rebuild the native app:

yarn install
cd ios
pod install
cd ..
yarn ios