This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Troubleshooting

Known issues, error decoder, and recovery procedures.

When something goes sideways, start here. If you don’t find the answer, ping Discord or send us a message.

Quick triage

  1. Does the same thing fail in a fresh project? — If yes, it’s an OPAL or engine issue. If no, it’s likely project state.
  2. Have you tried the operation outside OPAL? — For build/install failures, try the equivalent o3de.py command. If the CLI also fails, the issue is upstream of OPAL.
  3. Check the logs. — Every failed operation produces a log. Click View Logs on the project/queue item.

Common symptoms

“Missing engine” banner won’t go away

Caused by: the engine folder got moved or deleted externally.

Fix: Go to Engines, reinstall the missing version, or open the affected project’s Settings and assign it to a different installed engine.

Download is stuck at 0%

Caused by: network handshake failed silently, or the mirror is down.

Fix: Cancel the download, and reattempt. If it still fails, switch mirrors in Settings → Advanced → Download mirror (if multiple are available), or send us the log.

Build succeeds in CLI, fails in OPAL

Caused by: an environment variable is set in your shell but not inherited by OPAL.

Fix: Check Settings → Advanced → Environment variables and add any engine-required vars (e.g. VULKAN_SDK).

Queue shows duplicates after a crash

Caused by: the queue state file didn’t flush before the crash.

Fix: Click Clear completed to remove any completed duplicates. For active duplicates, cancel one of each pair. (We’re hardening this for a future release.)

Gem browser says “no gems” but a repo is configured

Caused by: the repo cache hasn’t been built yet, or the fetch failed.

Fix: Settings → Repositories → Refresh all. If that fails, the repo URL may be unreachable — open it in a browser to confirm.

Error decoder

ErrorMeaningFix
OPAL-E001Workspace directory not writablePick a different workspace in Settings
OPAL-E002Engine install checksum mismatchRetry; file an issue if it persists
OPAL-E010Project manifest missingEnsure project.json exists and is valid JSON
OPAL-E020Build: CMake configure failedOpen logs, fix the underlying CMake issue, retry
OPAL-E030Gem dependency unresolvableCheck the gem’s declared dependencies in its gem.json
OPAL-E040Queue state corruptionSee recovery below

Recovery: queue state corruption

If the Downloads or Builds page refuses to load after a hard crash:

  1. Close OPAL.
  2. Open the config directory (~/.opal/) and rename downloads-state.json / builds-state.json to *.json.bak.
  3. Restart OPAL. Queues will be empty; your engines and projects are untouched.
  4. Re-queue anything you still needed to download.
← Previous: Settings Next: FAQ →