Troubleshooting

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

Quick triage

1. Check the logs. Almost every failure leaves a log. Open the Logs page, or use View Log on the affected project, engine, or build.
2. Does it fail outside OPAL too? For a build or install failure, try the equivalent step with O3DE’s own o3de CLI. If the CLI fails as well, the issue is upstream of OPAL.
3. Does a fresh project reproduce it? If a brand-new project hits the same wall, it’s an engine/environment issue rather than your project’s state.

Common symptoms

A project shows a missing-engine warning

The engine the project points at can’t be resolved. OPAL tells you which of three cases it is and offers the fix on the card:

• Add Engine — the engine isn’t installed; install or download it.
• Register Engine — the engine is on disk but not registered with OPAL.
• Pin Engine — the engine resolved only by a loose name/version match; pin the exact one.

See Project status & health.

An engine shows “Invalid installation”

The engine’s files are missing or invalid. Use the row’s Redownload to reinstall it, or Remove to clear it out (removal goes to the recycle bin, so it’s recoverable).

A build fails

Open the build’s log from the Logs page or the build item’s View Log. CMake configure and compile errors are reported there. Fix the underlying issue and re-queue the build. If the same build succeeds with the o3de CLI but fails in OPAL, check that your build tools are detected correctly in Build Tools settings.

The Asset Library shows no gems

The repository cache may not have been built yet, or a fetch failed. Use the Asset Library’s Check for Updates / refresh button. If a repository still shows nothing, confirm its URL is reachable and ends in .json. See Repositories & sources.

A download won’t start or stalls

Cancel it and retry. Check that any required credentials were provided when prompted (for git-based gem sources). If a scheduled window is active, the download may be paused until the window opens — see Downloads.

Recovery: safe by default

OPAL is built so that interruptions don’t cost you work:

• Removing an engine or project moves it to the OS recycle bin / trash, not a permanent delete — so a mistaken removal is recoverable from there.
• Queues persist across launches; closing OPAL mid-operation and reopening restores the queue. If a queue looks wrong after an unclean shutdown, use Clear Completed and re-queue anything still pending.
• Your engines and projects are independent of the queues — clearing a queue never touches installed engines or registered projects.

If you hit something the above doesn’t cover, grab the relevant log from the Logs page and send it to us or share it on Discord.