Troubleshooting

The messages people meet on a first install or a first render, what they mean, and the fix. Each heading is the text you see.

version `GLIBC_2.39' not found (required by oxframe)

The prebuilt Linux binary of oxframe-cli 0.21.0 was built on a too new system and does not start on Debian 12, Ubuntu 22.04 and other distributions with an older glibc. The next release fixes it. Until then, build the command on your machine instead:

cargo install oxframe-cli

linker `cc` not found

Rust compiles your scene and then links it with the system C toolchain. A machine that has never built C or Rust code has none. Install it once:

sudo apt install build-essential   # Debian, Ubuntu
sudo dnf install gcc               # Fedora
sudo pacman -S base-devel          # Arch
xcode-select --install             # macOS

On Windows the error is linker `link.exe` not found: install the Visual Studio Build Tools with the Desktop development with C++ workload (rustup offers it when you install Rust), then open a new terminal.

cannot be built because it requires rustc 1.95 or newer

Your Rust is older than the SDK needs. Update it:

rustup update stable

ffmpeg was not found in PATH

oxframe render hands frames to ffmpeg to make MP4, WebM or ProRes. Install it, or point oxframe at a copy with ffmpeg = "/path/to/ffmpeg" under [render] in oxframe.toml:

sudo apt install ffmpeg         # Linux (or dnf / pacman)
brew install ffmpeg             # macOS
winget install Gyan.FFmpeg      # Windows, then open a new terminal

Everything else works without it: oxframe dev, oxframe check, oxframe snapshot and oxframe render --format png.

cannot listen on 127.0.0.1:3000 (another `oxframe dev`? use --port)

The editor's port is taken, usually by an oxframe dev still running in another terminal. Stop that one, or start this one elsewhere: oxframe dev --port 3001.

protocol versions differ

oxframe check stops with exit code 3 when the oxframe command and the project's SDK speak different editor protocols. Install the newest command, then move the project to it:

cargo install oxframe-cli
oxframe upgrade

See Versions and upgrades for what an upgrade changes.

build failed; the previous version keeps running

In oxframe dev this is not a crash. Your last save does not compile, so the editor keeps showing the last version that did. The compiler error is in the terminal; fix it and save, and the editor picks the new build up. A scene that panics again and again stops with project keeps crashing; fix the code and save to retry; the next save starts it again.

No GPU, or a server or CI runner

Nothing to do: frames are drawn on the CPU by default, so oxframe needs no graphics driver. --gpu asks for vello on Vulkan, Metal or DirectX 12 and falls back to the CPU when the machine has no usable adapter.

WSL

Install Rust and ffmpeg inside the Linux distribution, not on Windows. If oxframe dev cannot open a browser, copy the address it prints, token included, into the browser on Windows; WSL 2 forwards 127.0.0.1 to Windows by default. Keep projects in the Linux file system (~/…, not /mnt/c/…): builds and file watching are much faster there.

The disk fills up

Rust keeps each project's build cache in target/, a few gigabytes per project. Run cargo clean in a project you are not working on to get the space back; the next build starts from scratch.

Works locally, not in the playground

The browser playground builds with a fixed set of features. Video clips (video) and formulas (math) are not in it; scenes that use them run with oxframe dev on your machine.

Still stuck

Open an issue on GitHub with the command, its full output, oxframe --version and your system. Add -v to the command for detailed logs.

Edit this page on GitHub