AutoOrtho on Arch/CachyOS Linux – blue tiles fixed (source install)

[clumsynick]

Hi everyone,

I have already posted it on forums.x-plane.org but was encouraged to post it here, too:

had a really frustrating issue with AutoOrtho Continued (now 2.3.2) on my Linux machine and wanted to share the fix since I couldn't find anything about it online.

Setup: CachyOS (Arch-based), X-Plane 12, Ryzen 7 7800X3D / RTX 4080 16GB / 64GB RAM

The problem:

No matter what I tried, I kept getting blue/missing tiles during flight. The log was full of this every few seconds:

ERROR - Tile build lock timeout for (...) after 75s - returning fallback data
DIAGNOSTIC: ready=True, has_dds=True, budget=None

The weird part: has_dds=True means the tile is already built and sitting in cache — yet AutoOrtho can't serve it. Lowering texture quality in X-Plane did nothing.

What's actually going on:

The pre-built Linux binary doesn't properly bundle AoImage, the native library used to read tiles from disk cache. So every single cached tile read fails silently with:

WARNING - FallbackResolver: Could not import AoImage for disk cache fallback

The tile builder deadlocks waiting for something that will never come. On a fast machine this gets worse because X-Plane fires more concurrent tile requests.

The fix — run from source instead of the binary:

git clone https://github.com/ProgrammingDinosaur/autoortho4xplane.git ~/Games/autoortho-src
cd ~/Games/autoortho-src
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
sudo pacman -S --needed base-devel   # Arch/CachyOS only
make aopipeline

Quick sanity check:

python -c "from autoortho.aoimage import AoImage; print('OK')"

Start script:

#!/usr/bin/env bash
ulimit -n 524288
cd /home/YOUR_USER/Games/autoortho-src
source .venv/bin/activate
PYTHONPATH=/home/YOUR_USER/Games/autoortho-src/autoortho python -m autoortho &

When it's working you'll see this in the log on startup:

INFO - Loaded native decode library: aodecode 1.0.0 (OpenMP enabled) [Linux]
INFO - Loaded native DDS library: aodds 1.0.0 (OpenMP enabled) [ISPC] [Linux]
INFO - Loaded native cache library: aocache 1.1.0 (OpenMP) [Linux+fadvise]

Did a full flight after this — not a single blue tile, zero timeouts in the log.

This is probably specific to Arch-based distros since the binary is built on Ubuntu. If you're on Ubuntu and everything works fine, lucky you 😄

Hope this helps someone!

[karlrado]

Thanks for this! I made a PR #415 to add these instructions to the FAQ.

Running from the sources works fine on Ubuntu 26.04 without rebuilding the aoimage library.