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

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.
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.
Check the logs. — Every failed operation produces a log. Click View Logs on the project/queue item.

Common symptoms

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

Error	Meaning	Fix
`OPAL-E001`	Workspace directory not writable	Pick a different workspace in Settings
`OPAL-E002`	Engine install checksum mismatch	Retry; file an issue if it persists
`OPAL-E010`	Project manifest missing	Ensure `project.json` exists and is valid JSON
`OPAL-E020`	Build: CMake configure failed	Open logs, fix the underlying CMake issue, retry
`OPAL-E030`	Gem dependency unresolvable	Check the gem’s declared dependencies in its `gem.json`
`OPAL-E040`	Queue state corruption	See recovery below

Recovery: queue state corruption

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

Close OPAL.
Open the config directory (~/.opal/) and rename downloads-state.json / builds-state.json to *.json.bak.
Restart OPAL. Queues will be empty; your engines and projects are untouched.
Re-queue anything you still needed to download.

← Previous: Settings Next: FAQ →