Frequently Asked Questions (FAQ)

Common issues and solutions when using Pake.

Build Issues

Rust Version Error: "feature 'edition2024' is required"

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 dependency chain from tauri through image and moxcms to pxfm v0.1.25 requires Rust edition2024, which became stable in Rust 1.85.0 (released February 2025). If your Rust version is older (e.g., 1.82.0 from August 2024), you'll see this error.

Update your Rust toolchain to version 1.85.0 or later, then retry your build command:

# 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

A development environment needs:

Rust ≥1.85.0 (check with rustc --version)
Node.js ≥20.9.0 (check with node --version)

See Prerequisites for the full list.

Linux: Build Error "Can't detect any appindicator library"

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.

Ubuntu 24.04+ replaced libappindicator3-dev with libayatana-appindicator3-dev, so install the correct dependency:

sudo apt-get update
sudo apt-get install -y libayatana-appindicator3-dev

On Fedora and other RPM-based distros with the same error, install libappindicator-gtk3-devel:

sudo dnf install -y libappindicator-gtk3-devel

Linux: Installing on Fedora / RHEL / Oracle Linux (RPM-based distros)

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.

Pake 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 .rpm requires rpm-build (sudo dnf install rpm-build). If you only need a runnable app without packaging, add --keep-binary to also copy the raw executable next to the installer.

Linux: AppImage Build Fails with "failed to run linuxdeploy"

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, install all required system dependencies, then try building again:

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

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.AppImage afterwards.

Why This Happens:

This is a known issue with Tauri's linuxdeploy tool, which can fail when:

System libraries have incompatible formats for stripping
Building on newer distributions (Arch, Debian Trixie, etc.)
Missing WebKit2GTK or GTK development libraries

Linux: AppImage Crashes at Launch with WebKitNetworkProcess Not Found

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

Linux: AppImage Opens but Buttons or Keyboard Do Not Work on Wayland

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.

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: With WebKitGTK 2.52 or later, on both X11 and Wayland, Pake uses shared-memory rendering (WEBKIT_DMABUF_RENDERER_FORCE_SHM=1) instead of disabling the renderer, preserving the hardware acceleration needed for video. Older WebKitGTK versions keep the existing compatibility flags; niri keeps native rendering. Explicit WebKit variables are respected. PAKE_LINUX_WEBKIT_SAFE_MODE=1 selects the old conservative mode, while 0 removes the two disabling flags and skips automatic workarounds.

Linux: "cargo: command not found" After Installing Rust

You installed Rust but Pake still reports "cargo: command not found".

Pake CLI automatically reloads the Rust environment. If the issue persists, reload it or restart your terminal, then try building again:

# Reload environment in current terminal
source ~/.cargo/env

# Or restart your terminal

Windows: Installation Timeout During First Build

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:

Native module compilation (requires Visual Studio Build Tools)
Large dependency downloads (Tauri, Rust toolchain)
Windows Defender real-time scanning
Network connectivity issues

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

Use a stable network connection
Temporarily disable antivirus software during installation
Use a VPN or proxy if needed

Expected Time:

First installation: 10-15 minutes on Windows
Subsequent builds: Much faster (dependencies cached)

Windows: Missing Visual Studio Build Tools

Build fails with errors about missing MSVC or Windows SDK.

Install Visual Studio Build Tools:

Download Visual Studio Build Tools
During installation, select "Desktop development with C++"
For ARM64 support: Also select "MSVC v143 - VS 2022 C++ ARM64 build tools" under Individual Components

macOS: Build Fails with Module Compilation Errors

On macOS 26 Beta or newer, you may see errors related to CoreFoundation or _Builtin_float modules.

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.

Runtime Issues

App Window is Too Small/Large

Specify custom dimensions when building:

pake https://example.com --width 1200 --height 800

See CLI Usage Guide for all window options.

App Icon Not Showing Correctly

Custom icon doesn't appear or shows default icon.

Ensure you're using the correct icon format for your platform:

macOS: .icns format
Windows: .ico format
Linux: .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.

Some website features don't work in the Pake app.

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, so use the normal browser, a browser-installed app, or a native desktop client for those sites.

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. On macOS and Linux, other sign-in popups open in the current window instead, because the WebKit webview there can crash on them or drop them silently; on Windows they stay popups.

Passkeys and Touch ID sign-in are not available in Pake apps on macOS, because the system only offers them to browsers and to apps tied to the site's domain. Sign in with a password and a two-factor code instead.
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. As with item 4, use the site in a regular browser or a native client when it gates behind such a check.

App Uses More Memory Than Expected

The app spawns a WebKitWebProcess (Linux) or WebContent process (macOS) that uses several hundred MB of RAM, which seems to contradict the README's "typically under 10 MB" figure.

Explanation:

That number is the installer 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.

Installation Issues

Permission Denied When Installing Globally

npm install -g pake-cli fails with permission errors.

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

Getting Help

If your issue isn't covered here:

Check the CLI Usage Guide for detailed parameter documentation
See Advanced Usage for prerequisites and system setup
Search existing GitHub issues
Open a new issue with:
- Your OS and version
- Node.js and Rust versions (node --version, rustc --version)
- Complete error message
- Build command you used

Frequently Asked Questions (FAQ)

Build Issues

Rust Version Error: "feature 'edition2024' is required"

Linux: Build Error "Can't detect any appindicator library"

Linux: Installing on Fedora / RHEL / Oracle Linux (RPM-based distros)

Linux: AppImage Build Fails with "failed to run linuxdeploy"

Linux: AppImage Crashes at Launch with WebKitNetworkProcess Not Found

Linux: AppImage Opens but Buttons or Keyboard Do Not Work on Wayland

Linux: "cargo: command not found" After Installing Rust

Windows: Installation Timeout During First Build

Windows: Missing Visual Studio Build Tools

macOS: Build Fails with Module Compilation Errors

Runtime Issues

App Window is Too Small/Large

App Icon Not Showing Correctly

Website Features Not Working (Login, Upload, etc.)

App Uses More Memory Than Expected

Installation Issues

Permission Denied When Installing Globally

Getting Help