Troubleshooting

General build issues

• If a wrapper exits with the following message, pass a profile explicitly.

  error: a nix profile is required. pass it with -p or --profile.
  

  Example:

  ./nix-android.sh -p android-r27d
  

• If an Android build fails with ANDROID_TOOLCHAIN is not set, ANDROID_NDK_ROOT is missing, or a similar SDK/NDK error, the Nix wrapper supplies Android SDK platform 34, build tools 35.0.0, CMake 3.22.1 and NDK r27d:

  ./nix-android.sh -p android-r27d
  

  If you use scripts/start-android.sh directly, set ANDROID_SDK_ROOT and ANDROID_NDK_ROOT first, or pass a valid toolchain with --toolchain=path.

• If an Apple build fails because Xcode cannot be found, or because the detected Xcode version is too old, select a supported Xcode installation. The Nix xcode26 profile requires Xcode 26.x or newer.

  export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
  ./nix-ios.sh -p xcode26
  

  If you use scripts/start-ios.sh, scripts/start-macos.sh, scripts/start-tvos.sh or scripts/start-visionos.sh directly, the same DEVELOPER_DIR or xcode-select setup must be valid in your shell before running the script.

• If a build fails after source files were partially downloaded, patched, or generated, rebuild only the affected library first. The top-level scripts support these advanced options:

  • --rebuild-LIBRARY builds a library even if it is already installed.
  • --reconf-LIBRARY regenerates Autotools build files before building that library.
  • --redownload-LIBRARY downloads the source again even if it is already present.

  --rebuild-LIBRARY does not enable the library. Keep the matching --enable-LIBRARY option in the same command when the library is optional.

Host tool errors

• If gnutls or another Autotools-based source fails with a missing generated file, such as:

  CC       parse-datetime.lo
  clang: error: no such file or directory: 'parse-datetime.c'
  clang: error: no input files
  

  first make sure the build is using a new enough bison. The Nix wrappers provide bison and write the selected tool path to build.log.

  With Nix:

  ./nix-android.sh -p android-r27d --enable-gnutls --reconf-gnutls --rebuild-gnutls
  

  With host tools:

  export BISON=/path/to/bison
  "$BISON" --version
  ./scripts/start-android.sh --enable-gnutls --reconf-gnutls --rebuild-gnutls
  

  If the source tree was generated before fixing bison, keep --reconf-LIBRARY in the next build so the generated files are recreated.

• If a Meson based library fails with an error like the following, the build is usually using the wrong host Meson or missing the generated cross file.

  meson.build:25:0: ERROR: Could not invoke sanity test executable: [Errno 8] Exec format error: '.../sanitycheckc.exe'
  

  The Nix wrappers provide meson and ninja.

  With Nix:

  ./nix-android.sh -p android-r27d --enable-dav1d --rebuild-dav1d
  

  With host tools:

  export MESON=/path/to/meson
  "$MESON" --version
  ninja --version
  ./scripts/start-android.sh --enable-dav1d --rebuild-dav1d
  

  If the previous attempt left a stale source checkout, add --redownload-dav1d; otherwise --rebuild-dav1d is enough because the dav1d build directory is recreated on each run.

• If autoreconf fails because autopoint cannot be found:

  Can't exec "autopoint": No such file or directory
  autoreconf: autopoint is needed because this package uses Gettext
  

  the Nix profiles include gettext and set ACLOCAL_PATH.

  With Nix:

  ./nix-ios.sh -p xcode26 --enable-gnutls --reconf-gnutls --rebuild-gnutls
  

  With host tools, install gettext, make sure autopoint is in PATH, and set ACLOCAL_PATH if your package manager does not expose gettext's m4 files automatically:

  export PATH="/usr/local/opt/gettext/bin:$PATH"
  export ACLOCAL_PATH="/usr/local/opt/gettext/share/aclocal:$ACLOCAL_PATH"
  which autopoint
  ./scripts/start-ios.sh --enable-gnutls --reconf-gnutls --rebuild-gnutls
  

  On Apple Silicon Homebrew installations, replace /usr/local/opt/gettext with /opt/homebrew/opt/gettext. On Linux, use the gettext and autopoint paths installed by your distribution.

Library-specific issues

• If gnutls fails with the following error, rebuild its crypto dependencies and then gnutls.

  configure: error: Nettle lacks the required rsa_sec_decrypt function
  

  Example for Android:

  ./nix-android.sh -p android-r27d --enable-gnutls --rebuild-gmp --rebuild-nettle --rebuild-gnutls
  

  If the source checkout is stale or submodules were interrupted, add --redownload-nettle --redownload-gnutls.

• If kvazaar fails on a first build or after an interrupted Autotools generation, rebuild it with a fresh autoreconf.

  ./nix-android.sh -p android-r27d --enable-kvazaar --reconf-kvazaar --rebuild-kvazaar
  

  The current build scripts already run kvazaar without parallel make, so repeated failures usually indicate stale generated files rather than a parallel build race.

• If fontconfig fails with unresolved uuid_* symbols, rebuild libuuid and fontconfig.

  undefined reference to 'uuid_unparse'
  undefined reference to 'uuid_parse'
  undefined reference to 'uuid_copy'
  

  Android example:

  ./nix-android.sh -p android-r27d --enable-fontconfig --rebuild-libuuid --rebuild-fontconfig
  

  Apple builds use platform-specific libuuid library names:

  ./nix-ios.sh -p xcode26 --enable-fontconfig --rebuild-ios-libuuid --rebuild-fontconfig
  ./nix-macos.sh -p xcode26 --enable-fontconfig --rebuild-macos-libuuid --rebuild-fontconfig
  ./nix-tvos.sh -p xcode26 --enable-fontconfig --rebuild-tvos-libuuid --rebuild-fontconfig
  ./nix-visionos.sh -p xcode26 --enable-fontconfig --rebuild-visionos-libuuid --rebuild-fontconfig
  

  If libass is enabled in the same build, include --rebuild-libass as well because it depends on fontconfig.

• If xvidcore fails with a filesystem error such as install: mkdir ... File exists, rerun the build for xvidcore.

  ./nix-android.sh -p android-r27d --enable-gpl --enable-xvidcore --rebuild-xvidcore
  

  The current scripts build xvidcore serially. This error is normally left over from an interrupted or stale build directory.

When to redownload

Use --redownload-LIBRARY when a source checkout is corrupted, a submodule update failed, or a library was downloaded before the current ffmpeg-kit-next patch set was applied. Use --reconf-LIBRARY when configure, Makefile.in, aclocal.m4, or other generated Autotools files are stale. Use --rebuild-LIBRARY when installed artifacts under prebuilt are stale or were built with different options.