Limitations and Troubleshooting
Start with the error shown by Ephervex. For a failed game or server run, keep the log and crash report from that run before changing files. The Diagnostics guide explains how to inspect them and create a bundle if you need to share the problem.
Check the local setup
- Desktop
- CLI
Open the affected client or server, then select Diagnostics > Diagnose.
Read the findings and What was checked. A suggested fix shows its changes
before you apply it. If Ephervex itself cannot start, use the CLI doctor
command below.
Run these commands in the same environment you use to launch Ephervex:
ephervex doctor
ephervex paths
doctor checks local storage, configuration, credentials, bundled data, and
Java without downloading or launching Minecraft. paths shows the directories
Ephervex actually uses. For an AppImage, replace ephervex with its file name,
for example ./Ephervex-x86_64.AppImage doctor.
Find the next step
| Problem | What to check |
|---|---|
The AppImage cannot mount or find fusermount | Run it with APPIMAGE_EXTRACT_AND_RUN=1, as shown below. |
| A Minecraft or loader version is unavailable | Check the supported scope and the exact release and loader pairing. Ephervex will not choose a substitute. |
| A Forge 1.12.2 build or an ARM launch is refused before installation | Forge builds for 1.12.2 older than 14.23.5.2851 use an unsupported installer format; choose a newer build. On ARM, versions that select x86 natives are refused. See the supported scope. |
| Java is missing or the wrong version | Check the host's Java pill or its Java runtime card (instances, servers), then choose a compatible runtime or use Install Java N. After installing Java yourself, select Refresh Runtimes in Java settings. |
| A Microsoft account says sign-in is required | Check the account status and credential store. A session-only sign-in does not persist. |
| An import waits for a CurseForge file | Follow the manual download flow. The release already includes CurseForge API access. |
| A mod file is missing or damaged | Verify recorded files, then repair files with a recorded download source. |
| A client or server crashes | Read its logs and crash report, then diagnose the failed run. |
| A server says it needs attention after an interruption | Check server recovery before starting it again. |
| A download fails or an offline launch needs a file | Check the connection and what works offline. Missing artifacts must be fetched before an offline launch. |
| Favorites, groups, and icons could not be read | If the message names a kept file, Ephervex restored the copy from before the last change, or started empty if that copy was unusable too. Otherwise, check that organization.json in the data directory is readable. See file locations. |
| Storage or configuration cannot be written | Run ephervex doctor and check the resolved directories with ephervex paths. See file locations. |
The AppImage or desktop will not start
Use the build for your architecture: x86_64 or aarch64, as reported by
uname -m. Ephervex requires glibc 2.35 or newer (for example, Ubuntu 22.04
or Debian 12). The desktop needs X11 or XWayland. A Wayland-only session
without XWayland is untested; file drag and drop also needs X11 or XWayland.
If the AppImage reports a FUSE mount error, run it without mounting:
APPIMAGE_EXTRACT_AND_RUN=1 ./Ephervex-x86_64.AppImage
Use the aarch64 file name for the ARM build. This mode unpacks the AppImage
on each start, so startup is slower. See Installation for package
options and system requirements.
If an ephervex:// link does not open an AppImage, check its handler with
./Ephervex-x86_64.AppImage url-handler status. Register it again after moving
the AppImage. The import guide has
the registration command.
Supported scope
Ephervex runs on Linux x86_64 and aarch64. On x86_64, it supports Minecraft
release versions 1.12.2 and newer with Vanilla, Forge, or NeoForge. Forge or
NeoForge must have a build for the exact Minecraft release selected. Forge
builds for Minecraft 1.12.2 older than 14.23.5.2851 use an older installer
format; they are left out of build lists and refused when chosen by exact
version or pinned by a pack.
On ARM, the selected Minecraft version also needs compatible LWJGL natives in its metadata. Versions that select x86 natives, including Vanilla 1.12.2, 1.20.1, and 1.21.1, are refused before installation, and Ephervex does not substitute native downloads or change the selected versions. ARM launches have not yet been tested.
Fabric, Quilt, Minecraft snapshots, pre-releases, release candidates, Windows, and macOS are unsupported. Prism and MultiMC exports cannot be imported. The desktop interface is currently English only.
Some pack files require a manual download when their authors disable third-party downloads. Closing Ephervex stops its running clients and servers. Avoid concurrent mod changes on one client or server, including changes during an active mod isolation session.