How Vendor Boot Images Function in Treble-Enabled Android ROMs
Flashing a Treble ROM for the first time feels straightforward until the phone stops at the logo and refuses to go further. I have seen that exact moment on a Pixel and on a Xiaomi, and in both cases the system image was fine. The part that did not match was the vendor boot image. It is a small file with an outsized job, and getting it wrong is one of the most common reasons a Treble install never reaches the home screen.
This guide explains what the vendor boot image does, how it differs from the boot image and the vendor partition, and how to pair it with the right system, kernel and vendor version. It is written for people who flash custom ROMs, test generic system images, or maintain a device that already runs Treble. You will get concrete fastboot steps, pairing rules, log checks and a backup routine you can use before your next flash.
What a Vendor Boot Image Actually Contains in Treble Android
A vendor boot image is a bootable image that carries the early vendor side of Android startup. On Treble devices it usually holds a vendor ramdisk, a set of device tree blobs, and sometimes early kernel modules for vendor drivers. The vendor ramdisk contains the init scripts and binaries that start hardware services such as the camera provider, the audio service, the fingerprint sensor and the modem interface. Without those scripts running at the right moment, the system framework starts but cannot talk to the hardware underneath it.
The device tree blobs describe the hardware layout for the kernel: which chips sit on which bus, which regulators power the display, and which pins belong to the fingerprint reader. A wrong device tree can leave the screen dark, the touch panel silent, or the battery gauge reporting nonsense. Kernel modules in the vendor boot image load drivers that the main kernel image does not carry by itself, for example a display panel driver or a touch controller driver that is specific to one phone model.
Vendor ramdisk scripts and early hardware services
When the kernel finishes its earliest setup, it hands control to init, and init reads the vendor ramdisk scripts. Those scripts mount the vendor partition, start the vendor hardware abstraction layer services, and set permissions on device nodes under /dev. I think of this stage as the ignition sequence: the engine parts exist in the vendor partition, but nothing turns over until these scripts run. If a script fails, the matching service never registers with the system, and the symptom is usually a feature that is simply missing, such as a camera app that opens to a black preview or a fingerprint option that never appears in Settings.
How init finds vendor services at boot
Init reads the vendor init files, often named init.target.rc or similar, and starts each declared service in order. Services that depend on a device node wait until that node appears. A service that crashes on start gets restarted a few times, then the system gives up and logs the failure. That log trail is the fastest way to tell a vendor boot problem apart from a system problem, and I cover log capture later in this guide.
Device tree blobs and kernel modules in vendor boot
Device tree blobs, or DTBs, are compact descriptions of hardware that the kernel reads before it can use a peripheral. Treble devices often ship several DTBs in one vendor boot image, one per hardware revision, and the bootloader picks the matching one. Kernel modules extend the kernel without rebuilding it, which is why a vendor update can ship a new touch driver inside vendor boot while the main kernel stays the same. The trade-off is pairing: a module built for one kernel version may refuse to load on another, and a DTB written for one panel revision may drive a different panel badly.
Vendor Boot vs Boot vs Vendor Partition: Treble Split Explained
Classic Android used a single boot image for the kernel and the system ramdisk. Treble splits that job so the system side and the vendor side can update on different schedules. The boot image now holds the kernel and, on many devices, the system ramdisk. The vendor boot image holds the vendor ramdisk and the device tree pieces. The vendor partition holds the larger vendor libraries, firmware files, vendor apps and hardware abstraction layer binaries that those early services call into.
Mixing up these three pieces is the classic beginner error. Flashing a vendor boot image to the boot partition overwrites the kernel. Flashing a boot image to the vendor_boot partition leaves the vendor services without their startup scripts. Either mistake usually ends in a bootloop, and the fix is to reflash each file to its correct partition from a backup. Before every flash, I read the device layout with fastboot and confirm the partition names exist on that exact model and slot.
| Image or partition | What it holds | What breaks if it is wrong |
|---|---|---|
| boot | Kernel and system ramdisk | Phone never starts the kernel, or the system ramdisk fails |
| vendor_boot | Vendor ramdisk, device tree, early modules | Logo loop, missing camera, audio or sensors |
| vendor | Vendor libraries, firmware, HAL binaries | Services start but fail, features crash, calls drop |
| system | Android framework and apps | Setup crashes, interface errors, app failures |
Why the split makes generic system images possible
A generic system image, or GSI, is a system image built to run on many Treble devices. It can only do that because the vendor boot image and the vendor partition stay device-specific. The GSI brings the Android framework, the apps and the interface, while the vendor side brings the hardware knowledge. That division is the whole point of Treble: the system talks to vendor services through a stable interface, so one system build can serve phones from different makers as long as each phone supplies a matching vendor layer.
What a GSI still needs from your vendor layer
A GSI needs a vendor boot image that matches the vendor partition, a vendor interface version it supports, and a kernel that can load the vendor modules. It does not bring its own camera driver or modem firmware. If your vendor layer is older than the minimum the GSI notes ask for, expect missing features or a bootloop, even when the GSI itself is correct for your device.
How the Treble Vendor Interface Version Controls Boot Success
Treble defines a vendor interface, often called the VINTF, between the system and the vendor code. Each side declares the interface version it implements, and the system checks that declaration during boot. A system built for a newer interface may refuse to start vendor services from an older vendor layer, while a system built for an older interface can often run on a newer vendor layer. The vendor boot image carries the early part of that vendor side, so it must agree with the vendor partition version as well as with the system build.
ROM release notes usually state the required vendor version in plain language, for example “requires vendor from the March firmware” or “use vendor 14.0.3 or newer”. I treat that line as a requirement, not a suggestion. Flashing a ROM against the wrong vendor version is the single most common cause of the “ROM boots, but the camera is dead” report, and of the “everything works except mobile data” report. Both look like ROM bugs, and both are usually pairing errors.
To check your current vendor version before flashing, look at the firmware version in Settings, About phone, or read the build fingerprint from fastboot or recovery. Compare it with the ROM notes, not with a forum post from six months ago. Firmware moves on, and a pairing that worked on an older vendor build may not work on the newest one. Matching the vendor interface version before you flash saves more time than any recovery trick after a failed boot.
Reading VINTF and vendor version from your device
On a running Treble device you can check the vendor interface through the device info in Settings, or through a terminal command that dumps the VINTF manifest. In recovery, the vendor build properties file lists the vendor version directly. I keep a note of the vendor version alongside each ROM I test, because that pairing is what I need to reproduce a working setup months later. When a new vendor firmware lands, I update the note before I update the phone.
Flashing Vendor Boot with Fastboot: Exact Steps and Slot Checks
Fastboot is the normal tool for flashing a vendor boot image, and the command itself is short. The discipline around it is what matters. First, confirm the phone is in fastboot mode and the computer sees it with fastboot devices. Second, confirm the current slot with fastboot getvar current-slot, because A/B devices keep two copies of boot and vendor_boot, and flashing the inactive slot while the phone boots the active one changes nothing. Third, back up the existing boot and vendor_boot images before you overwrite them.
- Boot into fastboot mode from the bootloader menu or with
adb reboot bootloader, then runfastboot devicesand confirm your phone appears. - Run
fastboot getvar current-slotand note whether the active slot is A or B, so you flash the slot the phone will actually boot. - Back up the current images, for example by dumping boot and vendor_boot from recovery or by saving the stock files you flashed originally, labelled with model, slot and version.
- Flash the vendor boot image with
fastboot flash vendor_boot vendor_boot.imgand watch for a success message, not just a fast return to the prompt. - Flash the matching boot image with
fastboot flash boot boot.imgonly if the ROM or kernel notes say the pair belongs together. - Reboot with
fastboot rebootand watch the first boot closely; a first boot after a vendor change can take several minutes while caches rebuild.
If your device has no vendor_boot partition, do not force the command. Some older Treble devices and some devices with a combined boot image simply do not have one, and the correct procedure is the classic boot flash. Forcing a flash to a partition that does not exist fails in most cases without damage, but guessing partition names is a habit that eventually overwrites the wrong thing. For a speed comparison once the ROM is running, the guide on comparing custom ROM speed with stock firmware gives a useful baseline for judging whether the new setup is actually faster than the factory build.
Common fastboot mistakes with vendor_boot
The most frequent mistake is typing boot when you meant vendor_boot. The names look alike in a terminal, and the error only shows up at reboot. The second mistake is flashing an image built for a different codename, for example a file for the Pro model onto the standard model, where the device tree does not match the panel. The third is flashing a vendor boot image from a different Android version than the vendor partition, which breaks the interface pairing described above. A short pause to read the command aloud before pressing Enter catches most of these.
What to do when fastboot reports a partition error
If fastboot says the partition does not exist, stop and check the partition table for your device rather than trying a different spelling. If it says the image is too large, the file is almost certainly for a different device or a different layout. If the flash succeeds but the phone loops, reflash the backed-up vendor boot image first, before you change anything else, so you isolate the variable you just changed.
Vendor Boot and Kernel Pairing on Pixel, Xiaomi and OnePlus Treble Devices
Kernel updates often ship inside a new boot image, while vendor boot updates ship with vendor firmware. Those two files form a pair, and the ROM or kernel notes usually say which vendor version a kernel expects. A new kernel with an old vendor boot ramdisk may fail to start a service whose script changed. An old kernel with a new vendor boot ramdisk may refuse a module built for a newer kernel. Update the pair together whenever the notes pair them, and keep the previous pair on hand for rollback.
Pixel devices tend to document their vendor requirements clearly in the factory image notes, and their A/B slots make rollback a matter of switching slots. Xiaomi devices often need a specific vendor firmware from the regional build, and the wrong region can change modem behaviour. OnePlus devices have historically shipped kernel sources and vendor trees that lag the system release, so a custom kernel built against one vendor tree may not suit the next. The pattern is the same on all three: read the kernel vendor requirement, match it, and test with a backup ready.
Kernel managers that flash boot images automatically hide this pairing. I note the boot image version before I let a manager change anything, and I keep a manual backup outside the manager, because a manager that cannot restore the previous image leaves you with no net. A custom kernel is only as safe as the vendor boot image it is paired with.
When a kernel installer also touches vendor boot
Some kernel installers update the vendor boot image as part of their install script. Read the installer notes for any mention of vendor boot before you run it. If the installer expects a matching vendor partition, update the vendor firmware first, then run the installer. Vendor first, then kernel, is the safe order in that case, and the installer author chose that order for a reason.
Diagnosing a Vendor Boot Bootloop with Logs and Backups
A bootloop at the logo right after a vendor boot flash points at that image. Reflash the previous vendor boot image from your backup, and if the phone boots again, the new image was wrong for your device, your variant, or your vendor version. Check the codename, the hardware revision and the version number, then download the image for your exact variant. A bootloop after a system flash with an unchanged vendor boot points elsewhere: the system image may mismatch the vendor interface, so check the interface requirement and try a system build made for your vendor version instead of reflashing vendor boot at random.
Boot logs turn this guessing into diagnosis. A log can show a vendor service failing to start, a device tree error, or a missing kernel module. Capture logs through recovery or through fastboot tools where your device supports it, and compare a failing boot log with a successful boot log from the same device. A service present in the successful log but absent in the failing one is a suspect. A module loaded in success but missing in failure is another suspect. Keep one successful log as a reference, labelled with the ROM and vendor version it came from.
Encryption adds another layer after first boot. If the phone boots but asks for a passcode it never accepted, or if data stays unreadable after a vendor change, the guide on solving encryption and passcode problems after first boot walks through the recovery steps that fit that symptom, including when a data format is the only clean way forward and when a reflash of the matching vendor files fixes it without wiping.
Separating vendor boot faults from system faults
Stage awareness speeds every diagnosis. A failure before the boot animation usually sits in the bootloader, kernel, or vendor boot stage. A failure at the animation or at setup usually sits in the system stage. A failure where the home screen appears and then one feature crashes usually sits in the vendor partition or the app layer. Writing down which stage the phone reached before it failed is the first line of any useful help request, and it is what lets someone else point at the right file instead of guessing.
Scrubbing logs before you share them
Logs can contain serial numbers, account hints and network identifiers. Remove personal details before posting a log in a forum or chat. Helpers need the technical lines about services, modules and device tree errors, not your identifiers. A scrubbed log still diagnoses well, and it protects you while you ask for help.
Verified Boot, Signatures and Safety on Treble ROMs
Verified boot checks boot images before the bootloader loads them. The bootloader verifies signatures on the boot and vendor boot images, and a locked bootloader enforces that check. Custom ROM users usually run with a bootloader that permits custom images, which trades that verification for flexibility. That trade is worth understanding before you make it, because a tampered vendor ramdisk could start services you did not expect, and the verification layer that would have blocked it is no longer in the way.
Source hygiene replaces that lost layer. Download vendor boot images only from trusted sources, preferably the device maker, the ROM project, or a maintainer you can trace. Verify checksums when the source provides them, and be suspicious of a re-uploaded image with no checksum and no changelog. Relocking the bootloader can restore verification, but only with fully stock images in place: a custom vendor boot image will fail locked verification, and that failure can block the boot path entirely. Follow the maker relock guidance exactly, and never relock as an experiment.
Long-term safety is mostly organisation. Back up boot and vendor_boot images before every experiment, store them with labels for model, slot and version, and note each flash with its date and the system build it paired with. A labelled backup turns a bootloop into a ten-minute fix. An unlabelled backup invites a second mistake at the worst possible moment.
Choosing trusted vendor boot sources
Trust follows a chain: the device maker firmware, the ROM project release page, then a named maintainer with a public history. A random file link in a comment thread sits at the bottom of that chain. If two sources disagree about which vendor version a ROM needs, the ROM release notes win, because the ROM author tested that pairing.
Vendor Boot, GSI and MicroG: Practical Pairing Decisions
Treble also helps developers test Android versions early. A developer can flash a generic system image without building for one model, which speeds up app testing and lets enthusiasts preview new Android features. That preview value comes with rough edges: a generic image may lack device-specific polish, the camera may behave differently, and battery behaviour may not match a device-specific ROM. Treat a GSI as a preview unless it proves stable over a week of daily use on your device.
Once the system boots, the services question follows. Some users replace Google services with a lighter alternative to reduce background load or to run a system without a Google account. The guide on installing MicroG as a lightweight services alternative explains that setup, including which apps still need real Google services and which run fine on the replacement. That choice is independent of the vendor boot image, but it is worth deciding before you judge a new ROM, because a services change can look like a ROM performance change if you test both at once.
For a practical pairing routine, I use one sequence: confirm the vendor version, pick a system build that lists it, flash vendor boot and boot as a pair, boot once and check camera, calls, mobile data and sensors, and only then change kernels or services. Changing one variable at a time is slower in the moment and far faster across a month of flashing, because you always know which change broke what.
A weekly check for Treble devices that stay on custom ROMs
Once a week, check for a vendor firmware update from your maker, read the ROM changelog for any vendor requirement change, and confirm your backup still matches the images on the phone. That five-minute check catches a vendor drift before it becomes a bootloop on the next ROM update, and it keeps your rollback files honest.
Frequently Asked Questions About Vendor Boot Images
What happens if I flash a vendor boot image to the boot partition?
You overwrite the kernel with a file that is not a kernel, so the phone usually cannot start the kernel at all and stops very early in boot, often at the logo or on a black screen. The fix is to reflash the correct boot image to the boot partition and the vendor boot image to vendor_boot, both from files matched to your model and slot. This is exactly why a labelled backup of both images matters before any experiment.
How do I know which vendor version my Treble ROM needs?
Read the ROM release notes first, because they state the required vendor firmware or the minimum vendor version for that build. Cross-check with the vendor version shown in your phone settings or in the vendor build properties file. If the notes name a firmware month or a version number, match that number rather than guessing from a forum thread, and update the vendor firmware before you flash the ROM when the notes ask for a newer vendor.
Can a generic system image boot without a matching vendor boot image?
Usually it cannot boot cleanly, because the generic system relies on the vendor boot image to start the device-specific hardware services it needs. A mismatched vendor boot image may let the phone reach the logo and then loop, or it may boot with missing camera, audio or modem functions. Meeting the minimum vendor version in the generic image notes is the step that avoids most of those failures.
Why does my phone bootloop only after a kernel change?
A kernel change replaces the boot image, and the new kernel may expect a different vendor boot ramdisk or a module version that your current vendor boot image does not carry. Reflash the previous boot image first to confirm the kernel is the cause, then check the kernel vendor requirement and pair it with the vendor boot image the kernel author lists. Kernel managers that flash automatically can hide this pairing, so note the image version before each manager change.
Conclusion: Pair Vendor Boot Before You Flash
Vendor boot images look small next to a full ROM, but they decide whether Treble works at all on your phone. Match the vendor version to the ROM notes, flash vendor boot only to vendor_boot, keep boot and vendor boot as a tested pair, and keep a labelled backup of both before every change. Those four habits cover most of the failures I have seen, from logo loops to dead cameras.
Do one thing today: open your ROM notes, write down the vendor version they require, and compare it with the version on your phone. If they disagree, update the vendor firmware first, then flash. That single check, done before the flash instead of after the bootloop, is the difference between a ten-minute install and an evening spent recovering a phone.
