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: 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
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: 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: Automatic Retry (Built-in)
Pake CLI now automatically retries with CN mirror if the initial installation times out. Simply wait for the retry to complete.
Solution 2: Manual Installation
If automatic retry 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.
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)