# Troubleshooting AppFlowy Installation Issues: A Complete Guide to Common Fixes

> Resolve AppFlowy installation issues with this guide. Fix missing prerequisites permission errors and architecture mismatches for a smooth setup.

- Repository: [AppFlowy-IO/AppFlowy](https://github.com/AppFlowy-IO/AppFlowy)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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)](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)](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)](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)](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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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`:

  ```bash
  sudo ./install.sh
  ```

  Or use the `-b` flag to install in your home directory:

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

- **`Unsupported platform` error from [`install.sh`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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:

1. **Run the installer with debug output** to identify the exact failure point:

   ```bash
   ./install.sh -d
   ```

2. **Check for missing prerequisites** – Verify that `curl`, `wget`, `rustc`, `cargo`, and `flutter` are installed and in your `PATH`.

3. **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.

4. **Ensure write permissions** – Either run the installer with `sudo` or use the `-b $HOME/.local` flag to install in your home directory.

5. **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`).

6. **Configure Android builds** – After installing the NDK, export `ANDROID_SDK_ROOT` and `ANDROID_NDK_ROOT` to your `PATH` before invoking `flutter build apk`.

7. **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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/install.sh) script automates downloading and extracting the correct binary for your platform.

```bash

# 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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/install.sh) (lines 5-16):*

```sh
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.

```bash

# 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.

```bash

# 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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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.

```bash

# 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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/frontend/appflowy_flutter/android/README.md):*

```markdown
- 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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/README.md)** – The high-level installation guide that links to all supported methods (desktop, Docker, and source builds).

- **[`frontend/scripts/docker-buildfiles/README.md`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/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`](https://github.com/AppFlowy-IO/AppFlowy/blob/main/frontend/appflowy_flutter/android/README.md).