Skip to content
Avocado Extra Docs

Gotchas at a glance

Configuration

Section titled “Configuration”
  • Unknown keys are ignored silently, at every level. board: instead of target_board: does nothing. → Format
  • -r/--runtime doesn’t affect templating. {{ avocado.runtime }}, and a runtime’s target_board, come from AVOCADO_RUNTIME, then default_runtime. → Templating
  • {{ env.X }} with X unset becomes an empty string, not an error. That’s dangerous in password:. → Templating
  • A typo in an avocado.* template is left in place, braces and all, with no error. → Templating
  • Overlay files aren’t templated unless the overlay sets preprocess:. → Templating
  • {{ avocado.kernel.version }} only works in package keys. → Templating
  • Quote versions: version: 1.10 becomes "1". YAML 1.2: yes/no are strings. → Format
  • An unrecognized object in packages: is skipped without an error. → Format
  • Overrides replace lists; they don’t append, and a non-matching target-/kernel- key is dropped silently. → Overrides
  • rootfs.post_install replaces all the defaults, including the usrmerge symlinks and the empty machine-id. → Schema

Build

Section titled “Build”
  • Removing or renaming overlay files doesn’t remove them from the image, in merge or opaque mode. → Build state
  • Removing an enable_services entry leaves the service enabled. → Build state
  • Up-to-date checks only look at inputs. A bad image is reused until its inputs change. --no-stamps re-runs steps but doesn’t remove stale files. → Build state
  • Don’t type out the kernel version in package names. Use {{ avocado.kernel.version }}. → Kernel modules
  • avocado clean replaces the build volume, and docker run -v <old-name> creates an empty one. → Inspecting the volume
  • Templated kernel-module packages never make it into avocado.lock. → Build state
  • Two runtimes on one target share extension sysroots through a symlink that follows the last runtime installed. → Build state
  • Editing a compiled extension’s source doesn’t rebuild it unless the source is in package_files. → Build state
  • A git ref that isn’t a tag or branch builds the default branch. → Board variants
  • sdk:2024 is a moving tag. → Releases and channels

Device

Section titled “Device”
  • modules-load.d and sysctl.d in extensions don’t apply at boot. → Boot and merge
  • on_merge has no shell, and a missing program fails the whole merge, so no extension services start. → on_merge
  • A failed modprobe: only warns. → Kernel modules
  • networkd, resolved, modules-load.d and sysctl.d never see extension files at boot unless something orders them after the merge or reloads them. → Boot and merge
  • on_merge runs before D-Bus at boot, so networkctl reload and friends silently do nothing there. Use systemctl. → on_merge
  • A mask in an extension doesn’t stop that boot’s queued units, and prints [FAILED] for the masked unit. Put masks in the rootfs. → Boot and merge
  • modprobe: runs after daemon-reload, and changing only that list doesn’t rebuild the extension. → on_merge
  • machine-id is regenerated every boot, so ? hostnames and anything else derived from it change too. → Hostname and machine-id
  • Extension-only deploys don’t restart running services. The first reboot is the real test. → Deploy
  • Keep a login path that doesn’t depend on extensions. → Boot and merge

Jetson

Section titled “Jetson”
  • tegra-xudc loads late, so don’t gate a gadget on ConditionPathExistsGlob. → Jetson
  • usbhid is built in, and Ctrl+Alt+Del ×7 forces a reboot even when masked. → Jetson
  • nvidia-drm never loads by itself. → Jetson
  • The image ships a broken getty@.service link that loops as getty@getty at every boot. → Jetson
  • The RTC can pull the clock back to 1970 after the merge. → Jetson
  • The login console is ttyTCU0, not the ttyAMA0 kernel messages may use. → Boot and merge
  • The Orin NX BSP extension leaves out CAN, Wi-Fi and camera modules that the Nano’s has. → Carrier boards
  • carrier.env needs CARRIER_LABEL, or provisioning stops silently. → Carrier boards
  • nvbootctrl lives in the BSP extension. An empty BSP breaks the merge. → Jetson
  • Only the first carrier-bsp/ is used, whole, and a carrier BSP’s slot shadows one staged in the runtime build directory. → Carrier boards
  • A target flashes one module SKU. Another module (an 8GB Orin NX on jetson-orin-nx, for example) needs its own carrier.env values, and the image’s nvpmodel.conf stays the default SKU’s. → Carrier boards
  • kernel.cmdline_extra and the project’s initramfs: never reach a Jetson device, on either deploy or provision. → Jetson boot image
  • avocado deploy never carries the kernel or kernel DTB on Jetson, only the rootfs. Only a reflash (avocado provision) touches them. → Deploy