Troubleshooting

Last updated on

Three Stages of Errors

Polymerium classifies errors into three stages, each with different causes and solutions:

Stage 1: Deployment Failure  →  Game never started
Stage 2: Launch Failure      →  Java started but exited quickly
Stage 3: Runtime Crash       →  Game loaded but crashed

Identifying the stage is the first step to fixing the problem.

Stage 1: Deployment Failure

The deploy pipeline failed — Minecraft was never launched.

Network Issues

Symptoms: Timeout errors, checksum failures, "failed to resolve resource."

Fixes:

• Check your internet connection.
• Check proxy settings if repository or download requests cannot connect. The application update channel does not control game-file downloads.
• Retry the deploy — network issues are often transient.

Symlink Permission Issues (Windows)

Symptoms: "Failed to create symbolic link" errors during deploy.

Fixes:

• Confirm Developer Mode is enabled: Settings → System → For developers.
• Restart Polymerium after enabling Developer Mode.
• Check that no antivirus or sync tool is locking the build/ directory.

Filesystem Conflicts

Symptoms: "File already exists" or "Unexpected file in build directory."

Fixes:

• Stop the game and any tool writing to the instance, then retry deployment.
• Before using Reset or deleting build/, back up any saves, screenshots, or configuration stored only in the Run Directory. Reset permanently clears it; only files already in Local Data (persist/) are protected. See Directory Model.

Security Software

Symptoms: Deploy seems to hang, or files are deleted after being created.

Fixes:

• Add Polymerium's data directory to your antivirus exclusions.
• Disable real-time protection temporarily to test.

Stage 2: Launch Failure

Java started but the game exited immediately (usually within seconds).

Wrong Java Version

Symptoms: UnsupportedClassVersionError, "A JNI error has occurred."

Fixes:

• Check the Java version configured for this instance (see Java Management).
• Minecraft 1.20.5+ requires Java 21. Minecraft 1.18–1.20.4 requires Java 17.
• If no manual Java override works, remove it and check whether the instance has a compatible bundled runtime; native patches can narrow the acceptable Java versions.

Bad Launch Parameters

Symptoms: JVM exits with an error code, Could not create the Java Virtual Machine.

Fixes:

• Check memory allocation in Settings — don't allocate more than you have RAM.
• Remove custom JVM arguments if you've added any.
• Try the default settings.

Loader / Mod Conflicts

Symptoms: NoSuchMethodError, ClassNotFoundException, loader crash on startup.

Fixes:

• Verify the loader matches the Minecraft version.
• Check for mod version conflicts — a mod built for 1.21 won't work on 1.20.4.
• Try disabling half your mods, then re-enable in batches to isolate the conflict.

Stage 3: Runtime Crash

The game loaded but crashed during play.

Reading the Logs

1. Open the instance's Files tab.
2. Navigate to build/logs/latest.log for the main log.
3. Check build/crash-reports/ for crash report files.

Common Causes

Diagnostic Tools

Crash Report Modal

When a managed launch crashes, Polymerium shows a crash report with:

• Exit code
• Java version and path
• Allocated memory
• OS info
• Last 50 lines of log output
• Crash report file (if generated)
• Number of installed mods
• Full command line

Diagnostic Package

You can export a diagnostic package containing all relevant information. This is useful when asking for help — share the package with the developers or community.

AI Analysis Package

Polymerium can also export an AI-ready analysis package in Markdown format. The export first uploads your crash report and latest game log to mclo.gs — a third-party log-sharing service — to generate shareable links, then saves a Markdown file with those links, a log excerpt, the launch command line, and environment information. Polymerium confirms with you before anything is uploaded and redacts access tokens and usernames locally. Paste the file into an AI assistant (Claude, ChatGPT, etc.) for guided troubleshooting. Note that the uploaded logs are publicly accessible via their links and retained by mclo.gs.

Getting Help

For problems caused by documented deployment boundaries rather than a one-off failure, check Known Issues before filing a report.

1. Check the logs first — most errors are self-explanatory.
2. Try the fixes above for your error stage.
3. Export a diagnostic package and share it on GitHub Issues.
4. If using AI troubleshooting, export the AI analysis package and paste it into your assistant.