Project Won't Open

A .aether file fails to load - Aether either throws an error toast, silently reverts to an empty canvas, or hangs on open. This page walks through what to try.

Confirm the File Is Intact

First check: is the file the right size, and does it exist?

ls -la path/to/project.aether

Zero bytes means the save never completed - possibly an interrupted save or a disk full condition at write time. Non-zero but under 4 KB suggests a write failure that truncated the redb header. Both cases are unrecoverable without a backup; see § Last Resort below.

Check the Logs

~/Library/Logs/Aether/journal-<timestamp>.log captures every project-open attempt. The error is usually explicit; typical shapes:

  • "Database error: …" - wraps an underlying redb error (corruption, invalid tag, I/O). Redb has no built-in repair; recovery means restoring from a backup or rebuilding the patch by hand.
  • "File is from a newer version (X) than supported (Y)" - the file was saved by a different build of Aether. 0.1.0 does not guarantee forward- or backward-compat with other versions. See § Format Break.
  • "Deserialization error: …" - a node type referenced in the file no longer exists in this build, or its data layout changed. Same reasoning as a version mismatch.
  • "I/O error: …" - the file couldn't be read (permission, disk, or path issue).

A missing-log condition (no mention of the open at all) suggests the process never got far enough to log it. Retry with a fresh launch; if still silent, send the file to hello@voidrealm.com.

Format Break

.aether files in 0.1.0 are not promised stable. A file saved by a development build, a different 0.1.x release, or a future version may refuse to open.

There is no migration in this release. The only workaround:

  1. Find a build that opens the file. If the file was created by an older 0.1.x, install that build.
  2. Export as a Rhai script. Once open, run export_graph() in the console. This returns a plain-text Rhai script that re-creates the graph; save the output to a file.
  3. Open the script in the newer build. Scripts are the stable surface. The recovered .rhai file should run on any later version that has the same node types.

If the file was built by a version that cannot be reinstalled, the contents are effectively lost.

Hang on Open

Aether appears to start but never returns control. Causes seen in practice:

  • A node panics during graph construction. The audio-thread catches the panic and silences output for the rest of the session; the editor may still be waiting on a reply. Check ~/Library/Logs/Aether/crash-*.log for a panic trace.
  • A very large project. Projects with thousands of nodes or long sample references can take tens of seconds to load. Give it a minute before concluding the app is hung.

Force-quit (Cmd-Option-Esc) is safe during a load - the .aether file is read-only during open, so an interrupted load cannot corrupt it.

Last Resort

If the file cannot be recovered by any of the above, mail it to hello@voidrealm.com with a brief note describing what was in it. Worst case, the file cannot be opened - but diagnostics from the failure feed back into a more forgiving loader in the next release.

Prevention

  • Save patches as Rhai scripts before making risky changes. Scripts are diff-friendly and stable across releases. See Running Scripts and Working with Projects.
  • Version-control important projects. Even binary .aether files benefit from a git history - being able to go back to yesterday's file is often enough.
  • Working with Projects - save/open/autosave behaviour and backup strategies.
  • Crash Reports - related troubleshooting path when the app crashes instead of silently failing.