how-to-guide

Troubleshooting AppFlowy Installation Issues: A Complete Guide to Common Fixes

March 3, 2026 AppFlowy-IO/AppFlowy ↗

Most AppFlowy installation issues stem from missing prerequisites like curl, Rust, or Flutter, permission errors when writing to system directories, or architecture mismatches that can be resolved by using the -b flag for local installation or building from source.

AppFlowy combines a Rust core with a Flutter UI, creating multiple potential failure points during setup across Linux, macOS, Windows, Docker, Android, and iOS. Whether you are running the automated install.sh script or compiling from source, understanding the installation architecture is key to resolving AppFlowy installation issues quickly.

How the AppFlowy Installer Works

The AppFlowy repository provides several installation paths, each managed by specific components in the codebase:

install.sh – The primary Bash installer for Linux, macOS, and Windows (via WSL). Located at the repository root, this script parses flags (-b <bindir>, -d), detects the host OS and architecture, builds the download URL, fetches the tarball, extracts it, and launches the binary. See the usage() function in [install.sh](https://github.com/AppFlowy-IO/AppFlowy/blob/main/install.sh) for available options.
Docker – A self-contained image defined in [frontend/scripts/docker-buildfiles/README.md](https://github.com/AppFlowy-IO/AppFlowy/blob/main/frontend/scripts/docker-buildfiles/README.md). This pulls a pre-built binary for Linux x86_64 and wraps it in a container, eliminating the need for local Rust or Flutter toolchains.
Source Build (Desktop) – Requires building the Rust core with cargo and the Flutter UI with flutter. Build artifacts are placed under frontend/appflowy_flutter/production/<version>/. See the main [README.md](https://github.com/AppFlowy-IO/AppFlowy/blob/main/README.md) for high-level instructions.
Android / iOS – Requires cargo-ndk, the Android NDK, and a Flutter toolchain. The Rust library compiles to native .so or .a files and links to the Flutter project. Configuration details are in [frontend/appflowy_flutter/android/README.md](https://github.com/AppFlowy-IO/AppFlowy/blob/main/frontend/appflowy_flutter/android/README.md).

Common AppFlowy Installation Failures and Fixes

Missing Prerequisites

The install.sh script and build processes depend on standard Unix utilities and language toolchains.

command not found: curl or command not found: wget – The installer cannot download the tarball. Install the missing utility:
```
sudo apt-get install curl wget
```
On macOS, use brew install curl wget.
cargo: command not found or rustc: command not found – The Rust toolchain is missing. Install it:
```
curl https://sh.rustup.rs -sSf | sh
```
On macOS, you can also use brew install rust.

flutter: command not found – The Flutter SDK is not in your PATH. Clone the SDK and export it:

git clone https://github.com/flutter/flutter.git $HOME/flutter
export PATH=$HOME/flutter/bin:$PATH

Permission and Platform Errors

permission denied when moving AppFlowy to /opt – The script runs as a normal user but attempts to write to a privileged directory. Either run with sudo:
```
sudo ./install.sh
```
Or use the -b flag to install in your home directory:
```
./install.sh -b $HOME/.local
```
Unsupported platform error from install.sh – The OS or architecture is not recognized (e.g., non-x86_64 Linux). Build from source or use Docker instead.

Mobile Build Issues (Android)

cargo install cargo-ndk fails – Missing build dependencies like libssl-dev or pkg-config. Install them:
```
sudo apt-get install build-essential libssl-dev pkg-config
```

NDK not found or ANDROID_HOME not set – Environment variables are not exported. Add them to your shell configuration:

export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/<version>
export PATH=$PATH:$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools

Failed to link rust lib (missing librustc_driver) – The Rust target for the platform is not installed. Add it:
```
rustup target add aarch64-linux-android
```

Runtime and Container Issues

Docker: cannot start container (port already in use) – The host already runs an AppFlowy instance on port 3000. Stop the existing container or change the port mapping:
```
docker run -p 4000:3000 appflowy/appflowy
```
UI freezes on startup (blank screen) – The bundled Rust binary is not executable or required libraries like libssl are missing. Fix permissions and install libraries:
```
chmod +x $HOME/.local/AppFlowy/AppFlowy
sudo apt-get install libssl1.1 libz1
```
macOS: dyld: Library not loaded – macOS security blocks unsigned binaries. Remove the quarantine attribute or sign the binary:
```
xattr -c $HOME/.local/AppFlowy/AppFlowy
codesign -s - $HOME/.local/AppFlowy/AppFlowy
```

Step-by-Step Quick-Fix Checklist

Follow this sequence to isolate and resolve AppFlowy installation issues:

Run the installer with debug output to identify the exact failure point:
```
./install.sh -d
```
Check for missing prerequisites – Verify that curl, wget, rustc, cargo, and flutter are installed and in your PATH.
Verify architecture compatibility – Run uname -m. If the output is not x86_64 or aarch64, use Docker or build from source instead of the pre-built installer.
Ensure write permissions – Either run the installer with sudo or use the -b $HOME/.local flag to install in your home directory.
Validate Docker environment – If using Docker, ensure the Docker Engine is running (systemctl status docker) and that you have sufficient disk space (docker system df).
Configure Android builds – After installing the NDK, export ANDROID_SDK_ROOT and ANDROID_NDK_ROOT to your PATH before invoking flutter build apk.
Re-run the installation – After fixing the identified issue, re-execute the installer or the flutter build command.

Code Examples for Resolving AppFlowy Installation Issues

A. Install via the Provided Script (Linux/macOS)

The install.sh script automates downloading and extracting the correct binary for your platform.


# Download the script (or clone the repo)

curl -O https://raw.githubusercontent.com/AppFlowy-IO/AppFlowy/main/install.sh
chmod +x install.sh

# Run with debug to see each step

./install.sh -d

# If you lack sudo rights, install into your home directory

./install.sh -b $HOME/.local

Relevant snippet from install.sh (lines 5-16):

usage() {
  this=$1
  cat <<EOF
$this: download latest archive file for AppFlowy-IO/AppFlowy
Usage: $this [-b] bindir [-d] [tag]
  -b sets bindir or installation directory, Defaults to /opt
  -d turns on debug logging
   [tag] is a tag from https://github.com/AppFlowy-IO/AppFlowy/releases
EOF
  exit 2
}

B. Build from Source (Desktop)

When pre-built binaries are unavailable for your architecture, compile the Rust core and Flutter UI manually.


# 1️⃣ Install Rust & Flutter

curl https://sh.rustup.rs -sSf | sh
git clone https://github.com/flutter/flutter.git $HOME/flutter
export PATH=$HOME/flutter/bin:$PATH

# 2️⃣ Clone AppFlowy

git clone https://github.com/AppFlowy-IO/AppFlowy.git
cd AppFlowy

# 3️⃣ Build the Rust core

cargo build --release   # creates ./target/release/appflowy

# 4️⃣ Build the Flutter UI (desktop)

cd frontend/appflowy_flutter
flutter pub get
flutter build linux   # or macos / windows

C. Docker Installation (Any Platform with Docker)

Docker eliminates toolchain conflicts by running AppFlowy in a container.


# Build the image (optional – you can pull the pre‑built one)

docker-compose build --build-arg uid=$(id -u) --build-arg gid=$(id -g)

# Run the container

docker-compose up -d

# Access at http://localhost:3000

The Docker README at frontend/scripts/docker-buildfiles/README.md provides the full command reference.

D. Android Setup – Installing `cargo-ndk` and the NDK

Mobile builds require additional Rust tooling and Android SDK configuration.


# Install cargo‑ndk (Rust helper for Android)

cargo install cargo-ndk

# Install Android SDK & NDK (example for Ubuntu)

sudo apt-get install android-sdk android-ndk

# Export variables (add to ~/.bashrc)

export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/21.3.6528147
export PATH=$PATH:$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools

# Build the Android app

cd frontend/appflowy_flutter
flutter build apk

Reference snippet from frontend/appflowy_flutter/android/README.md:

- Install cargo-ndk ```bash cargo install cargo-ndk```.
- After installing the NDK tools for android you should export the PATH to your config file

Key Installation Files in the AppFlowy Repository

Understanding these files helps you pinpoint where failures occur in the installation pipeline:

install.sh – The central Bash installer for native binaries. Handles OS/architecture detection, download URL construction, tarball extraction, and binary execution. Located at the repository root.
README.md – The high-level installation guide that links to all supported methods (desktop, Docker, and source builds).
frontend/scripts/docker-buildfiles/README.md – Contains Docker build instructions and the pre-built image reference for containerized deployments.
frontend/appflowy_flutter/android/README.md – Details Android-specific toolchain requirements including cargo-ndk, NDK setup, and required environment variables.
frontend/appflowy_flutter/README.md – Covers Flutter project setup, required SDK versions, and how to run the UI from source.

Summary

Resolving AppFlowy installation issues requires systematically checking prerequisites, permissions, and platform compatibility:

Use the -d flag when running install.sh to enable debug output and identify exactly where the process fails.
Install locally with -b $HOME/.local to bypass permission errors instead of using sudo on system directories.
Verify toolchains before building from source—ensure cargo, rustc, and flutter are in your PATH.
Use Docker when your architecture is unsupported by pre-built binaries or when you want to avoid toolchain conflicts.
Export Android environment variables (ANDROID_SDK_ROOT, ANDROID_NDK_ROOT) before attempting mobile builds.

Frequently Asked Questions

Why does the AppFlowy installer fail with "permission denied"?

The install.sh script defaults to installing in /opt, which requires root privileges. Either run the script with sudo ./install.sh or specify a user-writable directory using the -b flag: ./install.sh -b $HOME/.local. The latter approach avoids permission issues entirely and keeps the application in your home directory.

How do I fix "Unsupported platform" errors when running the installer?

This error occurs when install.sh detects an architecture or operating system not covered by the pre-built release binaries (e.g., non-x86_64 or non-aarch64 systems). Resolve this by either using the Docker installation method, which runs independently of host architecture in many cases, or by building AppFlowy from source using cargo and flutter as documented in the repository's README.md.

What causes the AppFlowy UI to freeze or display a blank screen on startup?

A blank screen typically indicates that the bundled Rust binary lacks execute permissions or that required system libraries like libssl or libz are missing. Fix this by making the binary executable with chmod +x $HOME/.local/AppFlowy/AppFlowy and installing the missing libraries via your package manager (e.g., sudo apt-get install libssl1.1 libz1 on Ubuntu).

How do I resolve "NDK not found" errors when building for Android?

This error appears when the ANDROID_SDK_ROOT or ANDROID_NDK_ROOT environment variables are not set before running flutter build apk. Export these variables pointing to your actual SDK installation paths, for example: export ANDROID_SDK_ROOT=$HOME/Android/Sdk and export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/21.3.6528147. Ensure you also have cargo-ndk installed via cargo install cargo-ndk as specified in frontend/appflowy_flutter/android/README.md.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how AppFlowy-IO/AppFlowy works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →