Mengatasi Error UBA Executor UBT Unreal Engine pada UE 5.8 Source Build

Hampir tidak ada yang bisa menghentikan momentum studio game secepat build engine yang rusak, terutama saat Anda melakukan kompilasi Unreal Engine 5.8.0 dari source dan Visual Studio terhenti dengan exception yang misterius. Proses build gagal dengan unhandled exception yang mengarah langsung ke UBAExecutor.cs. Masalah spesifik ini, yang dikenal sebagai unreal engine uba executor ubt error, benar-benar menghentikan kompilasi. Bug ini memblokir build graph sehingga tidak dapat menyelesaikan pembuatan program pembantu (helper program) penting seperti UnrealHeaderTool. Dalam panduan ini, kami akan membedah mengapa Unreal Build Accelerator (UBA) bermasalah dengan pemanggilan nested (nested calls), bagaimana konfigurasi default-nya gagal, dan bagaimana cara melakukan patch pada engine source Anda untuk memulihkan build pipeline yang berfungsi kembali.

Memahami Arsitektur Build System

Untuk memahami mengapa error ini terjadi, kita harus mempelajari bagaimana Unreal Build Tool (UBT) mengatur proses kompilasi. Codebase Unreal Engine sangat besar, bahkan sering kali berisi puluhan ribu file source. Untuk mengompilasinya secara efisien, UBT bertindak sebagai meta-build system yang menghasilkan grafik dependensi (dependency graph) dan mengirimkan perintah kompilasi (compile action).

Apa itu Unreal Build Accelerator?

Epic Games memperkenalkan Unreal Build Accelerator (UBA) sebagai default compilation executor untuk menggantikan sistem distribusi yang lebih lama. UBA dirancang untuk mempercepat kompilasi dengan memanfaatkan virtualized file system (VFS) yang ringan untuk mengintersepsi operasi file I/O. Sistem ini mengarahkan tugas compiler ke berbagai core lokal atau mendistribusikannya melalui build node Horde.

Pada mesin build standar dengan 64 core, UBA dapat memangkas waktu kompilasi bersih (clean engine compilation) dari sekitar 90 menit menjadi di bawah 25 menit. Namun, karena UBA mengandalkan agen lokal terpusat untuk mengintersepsi I/O, UBA membutuhkan kontrol ketat terhadap bagaimana proses compiler dijalankan (spawned).

Mekanisme Pemanggilan UBT secara Rekursif (Recursive UBT Calls)

Selama proses kompilasi berjalan, UBT sering kali menemukan target yang harus di-build terlebih dahulu sebelum binary engine utama dapat dikompilasi. Sebagai contoh, sebelum mengompilasi file eksekutabel UnrealEditor, UBT harus mengompilasi UnrealHeaderTool (UHT) untuk mem-parsing file header dan menghasilkan metadata refleksi (reflection metadata).

Untuk melakukannya, proses UBT utama akan memicu (spawn) proses UBT sekunder yang bersarang (nested) untuk men-build target prasyarat tersebut. Pemanggilan bersarang ini disebut sebagai recursive UBT call. Ketika recursive UBT call aktif, UBT menyetel flag internal (UnrealBuildTool.IsRecursive = true) and meneruskan environment variable untuk menandai bahwa proses tersebut bersifat nested.

Mengapa UBA Executor Mengalami Crash pada Pemanggilan Rekursif

Crash terjadi karena arsitektur UBA executor tidak dirancang untuk mendukung loop kompilasi bersarang (nested compilation loops). Mari kita lihat call stack tipikal yang dikeluarkan oleh UBT saat kegagalan ini terjadi di Visual Studio:

Unhandled exception: Exception: UBA executor is not expected to be invoked from a recursive UBT call.
   at UnrealBuildTool.UBAExecutor.Init(IEnumerable`1 targetDescriptors, ILogger logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Executors\UnrealBuildAccelerator\UBAExecutor.cs:line 315
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state)
   at UnrealBuildTool.UBAExecutor.ExecuteActionsAsync(IEnumerable`1 inputActions, ILogger logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Executors\UnrealBuildAccelerator\UBAExecutor.cs:line 617
   at UnrealBuildTool.ActionGraph.InternalExecuteActions(ActionExecutor Executor, List`1 ActionsToExecute, ILogger Logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Actions\ActionGraph.cs:line 435

Pemeriksaan Keamanan (Safety Check) di UBAExecutor.cs

Di dalam method UBAExecutor.Init (sekitar baris 315 pada UBAExecutor.cs), engine secara eksplisit memberlakukan pemeriksaan keamanan rekursi (recursion safety check):

// Engine/Source/Programs/UnrealBuildTool/Executors/UnrealBuildAccelerator/UBAExecutor.cs
public void Init(IEnumerable<TargetDescriptor> TargetDescriptors, ILogger Logger)
{
    if (UnrealBuildTool.IsRecursive)
    {
        throw new Exception("UBA executor is not expected to be invoked from a recursive UBT call.");
    }
    
    // Virtualized file system and network initialization follow...
}

Pemeriksaan keamanan ini ada karena alasan yang sangat penting. UBA agent lokal mengikatkan diri (bind) ke port TCP spesifik untuk berkomunikasi dengan proses pembantu compiler (compiler helper processes) yang telah divirtualisasikan.

Jika pemanggilan UBT rekursif mencoba menginisialisasi instance kedua dari UBA executor, kedua instance tersebut akan mencoba melakukan bind ke network socket yang sama dan menyebabkan konflik pada virtualized file system hook. Hal ini akan mengakibatkan error alokasi socket (socket allocation error), kerusakan filesystem, atau deadlock proses build yang tidak terbatas. Exception ini berfungsi sebagai pelindung keamanan.

Penyebab Utama: Kegagalan Pemilihan Executor (Executor Selection Failure)

Bug sebenarnya pada source build Unreal Engine 5.8.0 bukanlah pemeriksaan keamanan tersebut. Melainkan, kegagalan logika executor factory dalam menangani pemanggilan rekursif dengan benar.

Saat UBT menentukan executor mana yang akan digunakan, ia memanggil class ExecutorFactory.cs. Factory tersebut akan memeriksa apakah UBA diaktifkan dan tersedia pada host machine.

Namun, ia tidak memverifikasi apakah proses UBT saat ini adalah sebuah eksekusi rekursif. Akibatnya, saat proses UBT sekunder berjalan untuk mengompilasi UnrealHeaderTool, factory mencoba menetapkan UBAExecutor pada nested build tersebut, yang akhirnya memicu crash pada method Init.

Jebakan Konfigurasi XML (XML Configuration Trap)

Banyak developer mencoba menghindari masalah ini dengan memodifikasi file global BuildConfiguration.xml. Saran standar di postingan forum lama adalah mematikan UBA dengan menonaktifkan tag berikut:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBA>false</bAllowUBA>
    </BuildConfiguration>
</Configuration>

Mengapa bAllowUBA Diabaikan di UE 5.8

Jika Anda menerapkan konfigurasi XML di atas pada source build Unreal Engine 5.8.0, compiler akan tetap mencoba menjalankan UBA dan melempar exception tersebut. Ini terjadi karena sistem build configuration milik engine telah di-refactor.

Flag lama bAllowUBA telah deprecated dan tidak lagi dipetakan ke logika pemilihan executor. Sekarang, perilaku UBA dikontrol oleh dua properti yang berbeda: bAllowUBAExecutor dan bAllowUBALocalExecutor.

Karena UBT tidak menemukan bAllowUBAExecutor di dalam XML Anda, nilainya secara default diatur ke true. Hal ini secara diam-diam membatalkan upaya Anda untuk mematikan UBA.

Struktur XML yang Benar untuk Konfigurasi UBA

Untuk berhasil menonaktifkan UBA melalui file konfigurasi, Anda harus menggunakan nama properti XML yang telah diperbarui. Di bawah ini adalah struktur yang benar untuk memaksa UBT melakukan fallback ke executor lokal standar:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBAExecutor>false</bAllowUBAExecutor>
        <bAllowUBALocalExecutor>false</bAllowUBALocalExecutor>
    </BuildConfiguration>
</Configuration>

Konfigurasi ini berhasil melewati UBA. Namun, menonaktifkan UBA sepenuhnya berarti Anda akan kehilangan peningkatan kecepatan kompilasi yang signifikan untuk build action utama Anda.

Panduan Langkah demi Langkah untuk Mengatasi Error

Tergantung pada workflow Anda, Anda dapat memilih untuk menyelesaikan masalah ini secara global dengan memodifikasi konfigurasi XML Anda, atau dengan melakukan patch pada source code UBT secara langsung untuk tetap mempertahankan akselerasi build pada kompilasi non-rekursif.

Metode 1: Override Menggunakan BuildConfiguration.xml

Jika Anda tidak ingin memodifikasi source code engine, Anda dapat menonaktifkan UBA secara global. Ini adalah cara tercepat agar project Anda dapat dikompilasi, meskipun ini akan meningkatkan waktu kompilasi untuk clean build sebesar ~40% hingga ~60% tergantung pada hardware Anda.

1. Cari atau buat file global BuildConfiguration.xml Anda. Pada Windows, file ini biasanya berada di %AppData%\Roaming\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml. Pada Linux, letaknya di ~/.config/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml.
2. Buka file XML tersebut menggunakan text editor.
3. Ganti konten di dalamnya dengan skema XML terbaru yang ditunjukkan di bawah ini.
4. Simpan file dan jalankan ulang build Visual Studio Anda.

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBAExecutor>false</bAllowUBAExecutor>
        <bAllowUBALocalExecutor>false</bAllowUBALocalExecutor>
    </BuildConfiguration>
</Configuration>

Metode 2: Melakukan Patch pada Source Code UBT (Direkomendasikan)

Karena Anda mengompilasi Unreal Engine 5.8 dari source, solusi yang direkomendasikan adalah melakukan patch pada source code C# UBT. Langkah ini memungkinkan UBA tetap berjalan pada target kompilasi utama Anda, sembari memaksa fallback ke ParallelExecutor standar saat pemanggilan rekursif terjadi.

1. Arahkan ke direktori source UBT: Engine/Source/Programs/UnrealBuildTool/Executors/.
2. Buka file ExecutorFactory.cs di Visual Studio atau text editor.
3. Cari method Create. Method ini bertugas mengevaluasi konfigurasi Anda dan mengembalikan ActionExecutor yang sesuai.
4. Modifikasi pernyataan kondisional pemilihan UBA untuk menyertakan pemeriksaan terhadap pemanggilan UBT rekursif.

// Engine/Source/Programs/UnrealBuildTool/Executors/ExecutorFactory.cs

public static ActionExecutor Create(BuildConfiguration BuildConfiguration, List<TargetDescriptor> TargetDescriptors, ILogger Logger)
{
    // Check if UBA is allowed, available, and NOT running recursively
-   if (BuildConfiguration.bAllowUBAExecutor && UBAExecutor.IsAvailable())
+   if (BuildConfiguration.bAllowUBAExecutor && UBAExecutor.IsAvailable() && !UnrealBuildTool.IsRecursive)
    {
        return new UBAExecutor(BuildConfiguration, Logger);
    }

    // Fall back to IncrediBuild if configured
    if (BuildConfiguration.bAllowXGE)
    {
        return new XGEExecutor(BuildConfiguration, Logger);
    }

    // Fall back to standard ParallelExecutor
    return new ParallelExecutor(BuildConfiguration, Logger);
}

Patch ini mencegah nested instance dari UBT untuk memilih UBA executor. Sebaliknya, recursive build (seperti build untuk UnrealHeaderTool) akan berjalan dengan aman menggunakan ParallelExecutor lokal, sementara kompilasi engine utama Anda tetap memanfaatkan performa penuh dari UBA.

Metode 3: Menggunakan Command Line Flags

Jika Anda menjalankan proses build melalui script command-line kustom atau pipeline CI/CD, Anda dapat menonaktifkan UBA per-pemanggilan (per-invocation). Cara ini sangat berguna jika Anda ingin tetap mengaktifkan UBA untuk para developer lokal tetapi menonaktifkannya pada remote build server.

Untuk melakukannya, tambahkan flag -NoUBA ke perintah build UBT Anda:

# Contoh perintah untuk men-build editor tanpa UBA
Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development -NoUBA

Sebagai alternatif, Anda dapat memaksa UBT untuk menggunakan parallel executor standar dengan menentukannya secara eksplisit menggunakan flag -Executor:

Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development -Executor=Parallel

Membersihkan dan Meregenerasi Build Environment

Setelah menerapkan salah satu solusi di atas, kompilasi UBT mungkin gagal akibat file assembly yang ter-cache atau metadata intermediate yang usang. Untuk memastikan perbaikan diterapkan secara bersih, Anda harus menghapus binary build tool yang dihasilkan dan meregenerasi file project.

Untuk Lingkungan Windows

Jalankan perintah berikut di command prompt atau instance PowerShell yang mengarah ke direktori source Unreal Engine Anda:

:: Delete the cached UBT assembly and build binaries
rd /s /q Engine\Intermediate\Build\UnrealBuildTool
rd /s /q Engine\Binaries\DotNET\UnrealBuildTool

:: Regenerate the project files
GenerateProjectFiles.bat

Untuk Lingkungan Linux dan macOS

Jalankan perintah berikut di terminal Anda:

# Remove cached build tool data
rm -rf Engine/Intermediate/Build/UnrealBuildTool
rm -rf Engine/Binaries/DotNET/UnrealBuildTool

# Regenerate project files
./GenerateProjectFiles.sh

Setelah environment bersih, buka file solution yang dihasilkan (UE5.sln) di Visual Studio dan lakukan rebuild pada target tersebut. Proses build sekarang seharusnya dapat melewati fase kompilasi rekursif tanpa memicu executor exception.

Best Practice yang Dapat Diterapkan untuk Unreal Engine Source Build

Membangun custom engine fork dari source menghadirkan berbagai tantangan kompilasi, optimasi, dan packaging. Menerapkan best practice berikut akan membantu Anda menjaga development pipeline tetap stabil dan teroptimasi dengan baik.

1. Optimasi Konkuransi untuk Mencegah Kurangnya Memori (Memory Starvation)

Compiler C++ modern membutuhkan RAM yang cukup besar untuk setiap thread kompilasi. Saat men-build modul engine yang besar, UBT dapat memicu lebih banyak tugas paralel daripada kapasitas RAM sistem Anda, menyebabkan page-file thrashing atau compiler crash.

Anda dapat membatasi jumlah prosesor maksimum dengan mengonfigurasi pengaturan ParallelExecutor di file BuildConfiguration.xml Anda:

<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <ParallelExecutor>
        <MaxProcessorCount>16</MaxProcessorCount>
        <ProcessorCountMultiplier>1.0</ProcessorCountMultiplier>
    </ParallelExecutor>
</Configuration>

Batasi jumlah tersebut menjadi sekitar 2 GB RAM per thread. Sebagai contoh, mesin dengan RAM 32 GB sebaiknya membatasi MaxProcessorCount ke angka 16.

2. Kuasai Asset Stripping pada Dedicated Server

Saat men-deploy game Anda ke cloud, sebaiknya hindari mengompilasi aset client yang tidak diperlukan (seperti tekstur UI, audio, dan mesh) ke dalam binary Dedicated Server Anda. Hal ini akan mengurangi waktu startup server dan ukuran memori (memory footprint), yang sangat penting untuk melakukan scaling fleet secara efisien.

Untuk mempelajari cara mengonfigurasi build script Anda untuk mengecualikan aset-aset ini, ikuti panduan detail kami tentang Unreal Engine Dedicated Server Asset Stripping.

3. Verifikasi Integritas Blueprint dan Paket Sejak Dini

Keberhasilan build engine tidak menjamin project Anda dapat melalui proses packaging tanpa error. Blueprint yang usang atau kesalahan serialisasi (serialization errors) sering kali menyebabkan crash pada fase packaging akhir.

Untuk mencegah masalah ini memblokir pipeline rilis Anda, baca panduan kami mengenai Resolving the Unreal Package HasValidBlueprint Ensure Crash untuk menyiapkan pemeriksaan validasi otomatis.

4. Konfigurasi UBA VFS Caching dengan Benar

Jika Anda memutuskan untuk tetap mengaktifkan UBA menggunakan patch C#, konfigurasikan virtual file system cache untuk menyimpan file objek kompilasi secara lokal. Ini memungkinkan Anda menghindari kompilasi ulang file source yang tidak berubah saat berganti branch.

Tambahkan blok konfigurasi UnrealBuildAccelerator ke file XML Anda untuk mengaktifkan caching:

<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <UnrealBuildAccelerator>
        <WriteCache>true</WriteCache>
        <Cache>127.0.0.1</Cache>
    </UnrealBuildAccelerator>
</Configuration>

Pastikan firewall Anda tidak memblokir port komunikasi jaringan lokal UBA, yang digunakan untuk mengelola loop sinkronisasi cache.

Meningkatkan Arsitektur Backend Anda

Mengatasi masalah build seperti unreal engine uba executor ubt error sangat krusial untuk menjaga kelancaran development workflow. Namun, menyiapkan lingkungan kompilasi lokal hanyalah langkah pertama dalam membangun game multiplayer modern.

Setelah custom engine Anda selesai dikompilasi dan dedicated server Anda siap, Anda harus menghadapi tantangan kompleks dari infrastruktur backend. Menulis sistem orkestrasi server, algoritme matchmaking, dan database persistensi Anda sendiri dari nol membutuhkan waktu pengembangan berminggu-minggu.

Menyiapkan load balancing, database sharding, dan manajemen sertifikat SSL dapat dengan mudah memakan waktu 4 hingga 6 minggu kerja keras. Dengan horizOn, layanan backend ini hadir secara terkonfigurasi (pre-configured) dan siap untuk di-scale.

Alih-alih menulis kode infrastruktur, Anda dapat mengintegrasikan data pemain, lobi real-time, dan penskalaan server hanya dengan beberapa panggilan API sederhana. Hal ini memungkinkan Anda men-deploy build dedicated server dan mengelola status pemain tanpa overhead pemeliharaan (maintenance overhead). Tim Anda dapat berfokus pada gameplay mechanic dan fitur engine sementara horizOn menangani infrastruktur cloud.

Langkah Selanjutnya

Untuk mengatasi error build ini, pilih antara melakukan override XML secara cepat atau menerapkan patch source C# di ExecutorFactory.cs. Setelah build pipeline berjalan lancar, carilah cara untuk mengoptimalkan deployment workflow Anda. Jika Anda ingin melakukan scaling pada game multiplayer Anda tanpa overhead hosting server kustom, coba horizOn secara gratis atau pelajari dokumentasi API kami untuk mengetahui lebih lanjut.

---

Sumber: Unhandled exception: Exception: UBA executor is not expected to be invoked from a recursive UBT call.