First: read the failure#

When a build fails, fpack prints the key error excerpt (Gradle's "What went wrong", Xcode errors, …), one concrete fix, and the path of the full log in build/fpack/logs/. Three tools help every time:

Tool	Use
fpack doctor	checks every prerequisite and prints the fix command for each
fpack build … --dry-run	shows every command without running it (passwords as ***)
-v / --verbose	streams the full tool output instead of an excerpt

Exit codes are explained on Exit codes and JSON.

Installation and startup#

Symptom	Cause and fix
command not found: fpack	~/.pub-cache/bin (Windows %LOCALAPPDATA%\Pub\Cache\bin ) is not on PATH : Installation
the first run says it falls back to a local build	the core could not be downloaded; check the network, FPACK_DOWNLOAD_URL , or use a bundled/offline install ( how the core is found )
macOS says the developer cannot be verified	fpack removes the quarantine attribute when it installs the core; if it is still blocked, run FPACK_REBUILD=1 fpack --version to build it with local Go
a local-path install prints "Resolving dependencies…" on every run	pub's fixed behavior for path-activated packages; install from pub.dev or git, or filter the lines when you consume --json
no Flutter project found in … or its parents	cd into the project or use fpack -C <dir> ; at a repository root fpack lists the Flutter apps below it
Flutter SDK not found	install Flutter, or --flutter <sdk> / FPACK_FLUTTER ; FVM projects are detected automatically ( Which Flutter? )
a path dependency is missing	fpack checks before building and names the package; put it at the expected relative path
which targets?	name targets ( fpack build apk ), use --all , or set build.targets
invalid configuration: …	fpack.yaml has a mistake; the message names the line and suggests the key. Reference

Output files#

Symptom	Cause and fix
already exists (a real run stops unless --force)	an artifact of this version exists: bump the version, --build-number N , or --force
needs macOS / needs Windows / needs Linux	Flutter cannot cross-compile; build on a runner of that OS ( concepts )
a target is skipped by --all	it needs a tool that is missing; fpack doctor says which

Android#

Symptom	Cause and fix
no Java (JDK 17+) found	install Android Studio (bundles a JDK) or JDK 17/21, then flutter config --jdk-dir <path>
keystore password was incorrect / alias … does not exist	check FPACK_ANDROID_KEYSTORE_PASSWORD / FPACK_ANDROID_KEY_ALIAS ; fpack verifies them with keytool before building
… defines productFlavors … but no flavor is set	pass --flavor or set build.flavor
flavor "x" not found	use one of the listed flavors; fpack doctor shows the detected flavors
release builds are signed with the DEBUG key	configure signing ( Android step 4 ); Google Play rejects debug-signed files
store_file is set but missing store_password	set FPACK_ANDROID_KEYSTORE_PASSWORD or android.signing.store_password

iOS#

Symptom	Cause and fix
no signing certificate / No Accounts	sign in to Xcode, or import the certificate and profile
No profiles for '…' were found	with manual signing list the bundle id (and extensions) in ios.provisioning_profiles
the team in a message is wrong	set ios.team_id; it wins over the project's DEVELOPMENT_TEAM
pod install failed	cd ios && pod install to see the error; pod repo update
duplicate build number on upload	bump +N or --build-number

See iOS.

macOS#

Symptom	Cause and fix
signing identity … not found in the keychain	use one of the listed Developer ID certificates exactly as printed, or build unsigned with --no-sign
notarization Invalid	fpack downloads Apple's log ( notary-log-<file>.json ) and summarizes the issues; usually unsigned nested code or a missing Hardened Runtime
upload timeouts while notarizing	fpack retries the upload twice; otherwise check the network and run the build again (nothing was submitted)
notarization takes long, you pressed Ctrl-C	Apple keeps processing: fpack notarize status, then fpack notarize finish
the signed app does not launch ( RBSRequestErrorDomain Code=5 , POSIX 163, "Launch failed")	restricted entitlements (push, iCloud, …) need a Developer ID provisioning profile: Provisioning profiles ; --smoke-test catches it before notarization
uses restricted entitlements … only with a provisioning profile , embeds Xcode's development profile , is a development/ad hoc profile , is not authorized by	see the validation table on Provisioning profiles
macOS log: Unsatisfied entitlements / No matching profile found	the profile does not cover the signature (wrong certificate, team, app id or entitlement value); fpack doctor names which
the app was not running … after launch (smoke test)	run the printed log show command; usually unauthorized entitlements or a crash at startup
pkg is unsigned	set macos.sign.installer_identity (the Developer ID Installer certificate)

Windows#

Symptom	Cause and fix
Inno Setup (ISCC.exe) not found	winget install --id JRSoftware.InnoSetup -e or set windows.inno_setup.iscc
Unable to read file … app.dill	the project path has non-ASCII characters: move it, or enable UTF-8 in the Windows region settings
signtool not found	install the Windows SDK ( winget install Microsoft.WindowsSDK.10.0.26100 ) or set windows.sign.signtool
signature verification warning	a self-signed certificate: only a warning; set windows.sign.verify: false to silence

Linux#

Symptom	Cause and fix
Linux desktop toolchain incomplete, missing: …	sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev
dpkg-deb / rpmbuild / appimagetool / snapcraft missing	install them (Linux); fpack lists every missing tool at once
snap needs sudo	run sudo -v first (or passwordless sudo as on CI), or use linux.snap.build_mode: lxd
snap: LXD not initialised	sudo lxd init --auto and add your user to the lxd group
the snap does not match the target CPU	it contains the bundle built on this machine: build arm64 snaps on arm64

Still stuck?#

Open an issue at github.com/Matkurban/fpack/issues with the output of fpack doctor, fpack --version and the log file named in the error (remove secrets first; fpack already redacts passwords).

先读失败信息#

构建失败时，fpack 会输出关键错误摘录（Gradle 的 “What went wrong”、Xcode 错误等）、一条具体的修复办法，以及 build/fpack/logs/ 里完整日志的路径。三个工具每次都有用：

工具	用途
fpack doctor	检查每个前置条件，并给出对应的修复命令
fpack build … --dry-run	显示每条命令但不运行（密码显示为 ***）
-v / --verbose	输出完整的工具输出，而不是摘录

退出码的含义见退出码与 JSON。

安装与启动#

症状	原因与修复
command not found: fpack	~/.pub-cache/bin （Windows 为 %LOCALAPPDATA%\Pub\Cache\bin ）不在 PATH 里： 安装
第一次运行提示回退到本机编译	核心下载失败；检查网络、 FPACK_DOWNLOAD_URL ，或使用内置/离线安装（ 核心如何被找到 ）
macOS 提示无法验证开发者	fpack 安装核心时会移除隔离属性；如果仍被拦截，运行 FPACK_REBUILD=1 fpack --version，用本机 Go 编译
本地路径安装每次都输出 “Resolving dependencies…”	pub 对路径激活的包的固定行为；改用 pub.dev 或 git 安装，或在处理 --json 时过滤这些行
no Flutter project found in … or its parents	cd 到项目里，或用 fpack -C <目录>；在仓库根目录 fpack 会列出下面的 Flutter 应用
Flutter SDK not found	安装 Flutter，或用 --flutter <sdk> / FPACK_FLUTTER ；FVM 项目会被自动检测（ 用哪个 Flutter？ ）
缺少 path 依赖	fpack 构建前会检查并指出包名；把它放在期望的相对路径
which targets?	写出目标（fpack build apk）、用 --all，或设置 build.targets
invalid configuration: …	fpack.yaml 有错误；信息会指出行号并提示可能的键。参考

输出文件#

症状	原因与修复
already exists (a real run stops unless --force)	这个版本的产物已存在：提高版本号、--build-number N，或 --force
needs macOS / needs Windows / needs Linux	Flutter 不能跨系统编译；在对应系统的 runner 上构建（ 概念 ）
某个目标被 --all 跳过	它需要的工具缺失；fpack doctor 会告诉你是哪个

Android#

症状	原因与修复
no Java (JDK 17+) found	安装 Android Studio（自带 JDK）或 JDK 17/21，然后 flutter config --jdk-dir <路径>
keystore password was incorrect / alias … does not exist	检查 FPACK_ANDROID_KEYSTORE_PASSWORD / FPACK_ANDROID_KEY_ALIAS ；fpack 构建前会用 keytool 验证
… defines productFlavors … but no flavor is set	传 --flavor 或设置 build.flavor
flavor "x" not found	使用列出的 flavor 之一；fpack doctor 会显示检测到的 flavor
release 构建用 DEBUG 密钥签名	配置签名（ Android 第 4 步 ）；Google Play 会拒绝调试签名的文件
store_file is set but missing store_password	设置 FPACK_ANDROID_KEYSTORE_PASSWORD 或 android.signing.store_password

iOS#

症状	原因与修复
没有签名证书 / No Accounts	在 Xcode 里登录，或导入证书和描述文件
No profiles for '…' were found	手动签名时，在 ios.provisioning_profiles 里列出 bundle id（以及扩展）
信息里的团队不对	设置 ios.team_id；它优先于项目里的 DEVELOPMENT_TEAM
pod install 失败	cd ios && pod install 查看错误；pod repo update
上传时构建号重复	提高 +N 或使用 --build-number

见 iOS。

macOS#

症状	原因与修复
signing identity … not found in the keychain	按列出的名字原样使用某个 Developer ID 证书，或用 --no-sign 构建未签名版本
公证结果 Invalid	fpack 会下载 Apple 的日志（notary-log-<文件>.json）并总结问题；通常是嵌套代码未签名或缺少 Hardened Runtime
公证时上传超时	fpack 会重试两次上传；否则检查网络并重新构建（什么都没提交）
公证时间很长，你按了 Ctrl-C	Apple 会继续处理：先 fpack notarize status，再 fpack notarize finish
已签名的应用打不开（RBSRequestErrorDomain Code=5、POSIX 163、“Launch failed”）	受限权限（推送、iCloud 等）需要 Developer ID 描述文件： 描述文件 ； --smoke-test 能在公证前发现
uses restricted entitlements … only with a provisioning profile 、 embeds Xcode's development profile 、 is a development/ad hoc profile 、 is not authorized by	见描述文件里的校验表
macOS 日志：Unsatisfied entitlements / No matching profile found	描述文件与签名不匹配（证书、团队、App ID 或权限值不对）；fpack doctor 会指出是哪一项
the app was not running … after launch（冒烟测试）	运行打印出来的 log show 命令；通常是未授权的权限或启动时崩溃
pkg 未签名	设置 macos.sign.installer_identity（Developer ID Installer 证书）

Windows#

症状	原因与修复
Inno Setup (ISCC.exe) not found	winget install --id JRSoftware.InnoSetup -e，或设置 windows.inno_setup.iscc
Unable to read file … app.dill	项目路径含有非 ASCII 字符：移动项目，或在 Windows 区域设置里启用 UTF-8
找不到 signtool	安装 Windows SDK（ winget install Microsoft.WindowsSDK.10.0.26100 ），或设置 windows.sign.signtool
签名验证警告	自签名证书：只是警告；设置 windows.sign.verify: false 可消除

Linux#

症状	原因与修复
Linux desktop toolchain incomplete, missing: …	sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev
缺少 dpkg-deb / rpmbuild / appimagetool / snapcraft	安装它们（Linux）；fpack 会一次列出所有缺失的工具
snap 需要 sudo	先运行 sudo -v（或像 CI 上那样免密 sudo），或使用 linux.snap.build_mode: lxd
snap：LXD 未初始化	sudo lxd init --auto，并把你的用户加入 lxd 组
snap 与目标 CPU 不匹配	它包含的是在本机构建的应用：arm64 的 snap 请在 arm64 上构建

还是解决不了？#

在 github.com/Matkurban/fpack/issues 提交 issue，附上 fpack doctor、fpack --version 的输出以及错误里提到的日志文件（先去掉机密；fpack 已经对密码做了脱敏）。