Skip to main content
Always try a clean build (cargo clean && cargo build --release) before reporting a bug. Many issues are caused by stale build artifacts.
Update your Rust toolchain, clean the build cache, and rebuild:
# Update Rust toolchain
rustup update

# Clean build cache
cargo clean

# Rebuild in release mode
cargo build --release
The app requires platform-specific build tools to compile.WindowsInstall Visual Studio Build Tools with the C++ build tools component:
winget install Microsoft.VisualStudio.2022.BuildTools
LinuxInstall the required packages for your distribution:
# Ubuntu/Debian
sudo apt update
sudo apt install build-essential pkg-config libssl-dev

# Fedora
sudo dnf install gcc gcc-c++ pkg-config openssl-devel

# Arch Linux
sudo pacman -S base-devel pkg-config openssl
macOSInstall Xcode Command Line Tools:
xcode-select --install
1

Check your internet connection

Ensure you have a working internet connection. The app needs to reach VRChat’s servers to download avatar databases.
2

Check firewall settings

Verify that your firewall is not blocking outbound HTTPS connections from the app.
3

Let the app retry

The app retries failed downloads automatically. Wait a moment and check if the download resumes.
4

Clear the cache and relaunch

If the download continues to fail, delete the cache/ directory and relaunch the app to start fresh:
# Remove cached database files
rm -rf cache/

# Relaunch the app
cargo run --release
  • Verify your credentials: Confirm your VRChat username and password are correct.
  • Check 2FA setup: If your account has two-factor authentication enabled, make sure you are entering the code from the correct authenticator app.
  • Cookie permissions: Ensure the app can read and write config.json in its working directory. Restricted file system permissions can prevent cookies from being saved.
Run the app with debug logging enabled to see detailed error output:
# Windows
set RUST_LOG=debug
prismic_avatar_search.exe

# Linux/macOS
RUST_LOG=debug ./prismic_avatar_search
Review the output in your terminal for error messages that identify the cause.
  • Check network connectivity: The app fetches avatar images from VRChat’s CDN. Confirm you have an active internet connection.
  • Re-login: Your auth cookie may have expired. Switch to the Login module from the top bar and log in again. A fresh session will restore image loading.
  • Verify the database was downloaded: Check that cache/avatar_entries.ndjson exists. If the file is missing, the Database Downloader module needs to run first. Relaunch the app or switch to the Database Downloader module manually.
  • Refine your search terms: Search scans avatar names, descriptions, and author names. Try shorter or more general keywords to confirm results are being returned at all.

​
Debug mode

Set the RUST_LOG environment variable to debug before launching to enable verbose logging: 
# Windows
set RUST_LOG=debug
prismic_avatar_search.exe

# Linux/macOS
RUST_LOG=debug ./prismic_avatar_search

Build docs developers (and LLMs) love

Get started for freeTalk to us