docs/faq.md
Common issues and solutions when using Pake.
Problem: When building Pake or using the CLI, you encounter an error like:
error: failed to parse manifest
Caused by:
feature `edition2024` is required
this Cargo does not support nightly features, but if you switch to nightly channel you can add `cargo-features = ["edition2024"]
to enable this feature
Why This Happens:
Pake's dependencies require Rust edition2024 support, which is only available in Rust 1.85.0 or later. Specifically:
tauri → image → moxcms → pxfm v0.1.25 (requires edition2024)Solution:
Update your Rust toolchain to version 1.85.0 or later:
# Update to the latest stable Rust version
rustup update stable
# Or install the latest stable version
rustup install stable
# Verify the update
rustc --version
# Should show: rustc 1.85.0 or higher
After updating, retry your build command.
For Development Setup:
If you're setting up a development environment, ensure:
rustc --version)node --version)See CONTRIBUTING.md for complete prerequisites.
Problem: When building on Ubuntu 24.04 or newer, you may encounter:
Can't detect any appindicator library
Or potentially errors related to Icon RGBA in older versions.
Solution:
Ubuntu 24.04+ replaced libappindicator3-dev with libayatana-appindicator3-dev.
Install the correct dependency:
sudo apt-get update
sudo apt-get install -y libayatana-appindicator3-dev
Problem:
On RPM-based distros (Fedora, RHEL, Oracle Linux, Rocky, AlmaLinux, openSUSE) a
.deb package cannot be installed by the system package manager, and older Pake
versions always built a .deb first.
Solution:
Pake now picks the default bundle target from /etc/os-release: RPM-based
distros default to rpm, appimage, while Debian/Ubuntu keep deb, appimage. So
the basic command already produces an installable package:
pake https://github.com --name GitHub
sudo dnf install ./GitHub.rpm # or: sudo rpm -i ./GitHub.rpm
You can also choose the format explicitly at any time:
pake https://github.com --name GitHub --targets rpm # RPM package
pake https://github.com --name GitHub --targets appimage # portable AppImage
When several targets build (the default), one format failing no longer aborts
the others: if the .rpm/.deb bundler fails, the AppImage is still produced as
a portable fallback. AppImage runs without installation:
chmod +x ./GitHub.AppImage
./GitHub.AppImage
Building an
.rpmrequiresrpm-build(sudo dnf install rpm-build). If you only need a runnable app without packaging, add--keep-binaryto also copy the raw executable next to the installer.
Problem: When building AppImage on Linux (Debian, Ubuntu, Arch, etc.), you may encounter errors like:
Error: failed to run linuxdeploy
Error: strip: Unable to recognise the format of the input file
ERROR: Failed to run plugin: gtk
cp: cannot stat '/usr/lib/gdk-pixbuf-2.0/2.10.0': No such file or directory
Identify which failure you have first. Two distinct problems share the failed to run linuxdeploy message:
strip: Unable to recognise the format of the input file: a strip incompatibility. Use Solution 1.Failed to run plugin: gtk together with cannot stat '/usr/lib/gdk-pixbuf-2.0/...': linuxdeploy's gtk plugin cannot find the gdk-pixbuf loaders. NO_STRIP will not help. Install the loaders, refresh the cache, then rebuild:# Arch
sudo pacman -S gdk-pixbuf2 librsvg
# Debian / Ubuntu
sudo apt install librsvg2-common gdk-pixbuf2.0-bin
# refresh the loader cache, then rebuild
gdk-pixbuf-query-loaders --update-cache
Solution 1: Automatic NO_STRIP Retry (Recommended)
Pake CLI now automatically retries AppImage builds with NO_STRIP=1 when linuxdeploy fails to strip the binary. To skip the strip step from the very first attempt (or when scripting your own builds), set the variable manually:
NO_STRIP=1 pake https://example.com --name MyApp --targets appimage
This bypasses the library stripping process that often causes issues on certain Linux distributions.
Solution 2: Install System Dependencies
If NO_STRIP doesn't work, ensure you have all required system dependencies:
sudo apt update
sudo apt install -y \
libdbus-1-dev \
libsoup-3.0-dev \
libjavascriptcoregtk-4.1-dev \
libwebkit2gtk-4.1-dev \
build-essential \
curl wget file \
libxdo-dev \
libssl-dev \
libgtk-3-dev \
libayatana-appindicator3-dev \
librsvg2-dev \
gnome-video-effects \
libglib2.0-dev \
libgirepository1.0-dev \
pkg-config
Then try building again (you can still pre-set NO_STRIP=1 if you prefer).
Solution 3: Use DEB Format Instead
DEB packages are more stable on Debian-based systems:
pake https://example.com --name MyApp --targets deb
Solution 4: Use Docker (with FUSE access)
Build in a clean environment without installing dependencies. AppImage tooling needs access to /dev/fuse, so run the container in privileged mode (or grant FUSE explicitly):
docker run --rm --privileged \
--device /dev/fuse \
--security-opt apparmor=unconfined \
-v $(pwd)/output:/output \
ghcr.io/tw93/pake:latest \
https://example.com --name MyApp --targets appimage
Tip: The generated AppImage may be owned by root. Run
sudo chown $(id -nu):$(id -ng) ./output/MyApp.AppImageafterwards.
Why This Happens:
This is a known issue with Tauri's linuxdeploy tool, which can fail when:
The NO_STRIP=1 environment variable is the official workaround recommended by the Tauri community.
Problem: The AppImage builds successfully but crashes immediately at launch:
** ERROR **: Unable to spawn a new child process: Failed to spawn child process
"././/lib/webkit2gtk-4.1/WebKitNetworkProcess" (No such file or directory)
This only affects AppImages built locally on a non-Debian distribution (Arch, Fedora, etc.). Pake's official AppImage releases are built in a Debian-based environment and are not affected.
Why This Happens:
This is an upstream Tauri bundler limitation (tauri-apps/tauri#5292). When bundling, Tauri rewrites the absolute WebKit helper path baked into libwebkit2gtk*.so to a relative ././... form, and copies the helper binaries based on the Debian library layout (/usr/lib/<arch-triple>/webkit2gtk-4.1). On Arch the helpers live in /usr/lib/webkit2gtk-4.1 with no architecture triple, so the patched relative path points at a lib/webkit2gtk-4.1 directory that does not exist inside the bundle, and WebKitNetworkProcess can never be found. Pake does not control this step: the AppDir layout and path patching are produced entirely by tauri build.
Solution 1: Use the Arch native package (recommended on Arch)
pake https://example.com --name MyApp --targets zst
This produces a pacman package (*.pkg.tar.zst) that installs to system paths, so WebKit resolves its helper processes natively and there is no relocation problem. Install it with sudo pacman -U MyApp-*.pkg.tar.zst.
Solution 2: Build the AppImage in Docker (Debian-based)
Building inside Pake's Docker image matches the library layout the AppImage bundler expects:
docker run --rm --privileged \
--device /dev/fuse \
--security-opt apparmor=unconfined \
-v $(pwd)/output:/output \
ghcr.io/tw93/pake:latest \
https://example.com --name MyApp --targets appimage
Workaround for an already-built AppImage:
Extract it, add the missing symlink, then launch the inner AppRun:
./MyApp.AppImage --appimage-extract
cd squashfs-root
mkdir -p lib && ln -s ../usr/lib/webkit2gtk-4.1 lib/webkit2gtk-4.1
./AppRun
Problem: On some pure Wayland compositors, especially niri, the AppImage can open but page buttons cannot be clicked or keyboard input does not reach the webview.
Solution: Pake automatically avoids the conservative WebKit rendering flags in niri sessions. To force the same native WebKit path manually, launch the app with:
PAKE_LINUX_WEBKIT_SAFE_MODE=0 ./MyApp.AppImage
If your system shows a blank window instead, re-enable the conservative WebKit workaround:
PAKE_LINUX_WEBKIT_SAFE_MODE=1 ./MyApp.AppImage
Why This Happens:
Pake normally enables WebKitGTK workarounds that help blank-window cases on Linux, but those same flags can make input and window controls unreliable on some Wayland compositors. The PAKE_LINUX_WEBKIT_SAFE_MODE variable lets you choose the safer rendering mode for your compositor.
Problem: You installed Rust but Pake still reports "cargo: command not found".
Solution:
Pake CLI automatically reloads the Rust environment, but if issues persist:
# Reload environment in current terminal
source ~/.cargo/env
# Or restart your terminal
Then try building again.
Problem: When building for the first time on Windows, you may encounter:
Error: Command timed out after 900000ms: "cd ... && pnpm install"
Why This Happens:
First-time installation on Windows can be slow due to:
Solution 1: Enable CN Mirror Explicitly
Pake CLI uses the official npm and Rust sources by default. If downloads are slow in China, opt in to CN mirrors:
# macOS/Linux
PAKE_USE_CN_MIRROR=1 pake https://github.com --name GitHub
# Windows PowerShell
$env:PAKE_USE_CN_MIRROR="1"; pake https://github.com --name GitHub
Solution 2: Manual Installation
If dependency installation still fails, manually install dependencies:
# Navigate to pake-cli installation directory
cd %LOCALAPPDATA%\pnpm\global\5\.pnpm\pake-cli@VERSION\node_modules\pake-cli
# Install with CN mirror
pnpm install --registry=https://registry.npmmirror.com
# Then retry your build
pake https://github.com --name GitHub
Solution 3: Improve Network Speed
Expected Time:
Problem: Build fails with errors about missing MSVC or Windows SDK.
Solution:
Install Visual Studio Build Tools:
Problem:
On macOS 26 Beta or newer, you may see errors related to CoreFoundation or _Builtin_float modules.
Solution:
Create a configuration file to use compatible SDK:
cat > src-tauri/.cargo/config.toml << 'EOF'
[env]
MACOSX_DEPLOYMENT_TARGET = "15.0"
SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
EOF
This file is already in .gitignore and won't be committed.
Solution:
Specify custom dimensions when building:
pake https://example.com --width 1200 --height 800
See CLI Usage Guide for all window options.
Problem: Custom icon doesn't appear or shows default icon.
Solution:
Ensure you're using the correct icon format for your platform:
.icns format.ico format.png format# macOS
pake https://example.com --icon ./icon.icns
# Windows
pake https://example.com --icon ./icon.ico
# Linux
pake https://example.com --icon ./icon.png
Pake can automatically convert icons, but providing the correct format is more reliable.
Problem: Some website features don't work in the Pake app.
Solution:
This is usually due to web compatibility issues. Try:
Set custom User Agent:
pake https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
Inject custom JavaScript:
pake https://example.com --inject ./fix.js
For pages that need periodic reloads, you can keep this behavior in a small injected script instead of adding a dedicated Pake option:
function isEditing(element) {
if (!element) return false;
const tagName = element.tagName;
return (
element.isContentEditable ||
tagName === "INPUT" ||
tagName === "TEXTAREA" ||
tagName === "SELECT"
);
}
setInterval(() => {
if (!document.hidden && !isEditing(document.activeElement)) {
window.location.reload();
}
}, 300000);
Save it as refresh.js and package with:
pake https://news.ycombinator.com --name HackerNews --inject ./refresh.js
Check if the site requires specific permissions that may not be available in WebView
Be aware of embedded-webview sign-in limits
Some authentication providers, especially Google, may block sign-in inside embedded webviews. Because Pake packages sites into a desktop webview, Google properties or sites that rely on Google OAuth may still fail to sign in even when --new-window or --multi-window is enabled. This is provider policy, not a packaging bug. In those cases, use the normal browser, a browser-installed app, or a native desktop client.
On macOS, Pake keeps Sign in with Apple popup flows (e.g. Yelp, Upwork) on the native popup path so Apple's callback can return to the opener page. Other auth popups may still be navigated in the current window to avoid WebKit crashes. If a provider blocks embedded webviews or the login still fails, use the normal browser, a browser-installed app, or a native desktop client.
WeChat Web login environment error
WeChat detects the WebView and writes a flag cookie that blocks subsequent logins. Add --incognito when packaging to bypass it, at the cost of requiring a QR scan on every launch:
pake https://wx.qq.com --name WeChat --incognito
Cloudflare or bot-verification loops forever
Some sites (e.g. ChatGPT) put a Cloudflare challenge in front of the page. The system WebView, especially WebKitGTK on Linux, is often flagged by these challenges and loops without passing, even with a custom --user-agent. This is the challenge provider detecting a non-standard browser engine, not a Pake bug, and there is no reliable Pake-side workaround. Use the site in a regular browser or a native client when it gates behind such a check.
Problem: The app spawns a WebKitWebProcess (Linux) or WebContent process (macOS) that uses several hundred MB of RAM, which seems to contradict the "~5MB" figure.
Explanation:
The ~5MB number is the installer/app size on disk, not runtime memory. At runtime Pake renders through your system WebView (WebKitWebProcess on Linux, WKWebView on macOS), and that process's memory is governed by the engine and the page you load, not by Pake. A heavy SPA like Gemini, Slack, or ChatGPT uses a comparable amount opening in any WebKitGTK browser such as GNOME Web. Pake adds very little on top of the WebView, so there is no Pake-side setting that meaningfully lowers it. This is inherent to using the system WebView and is the trade-off for the small binary size.
Problem:
npm install -g pake-cli fails with permission errors.
Solution:
Use one of these approaches:
# Option 1: Use npx (no installation needed)
npx pake-cli https://example.com
# Option 2: Fix npm permissions
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g pake-cli
# Option 3: Use pnpm (recommended)
pnpm install -g pake-cli
If your issue isn't covered here:
node --version, rustc --version)