commaai/openpilot · error · RuntimeError

flash.py must run as root

Error message

flash.py must run as root

What it means

flash.py's main() checks os.geteuid() != 0 and refuses to run as a non-root user. Flashing the chestnut requires raw access to the device node and USB stack (open/send of bulk transfers, runtime-PM control under /sys), which Linux grants only to root. This is a deliberate guard before any hardware operation starts.

Source

Thrown at openpilot/system/hardware/chestnut/flash.py:567

        program_sector(flash, addr, wanted)

    verified = stable_read(flash, first_sector, span - first_sector, 3)
    if verified != target:
      raise RuntimeError("final full-image verification failed")
    print(f"verified sha256={hashlib.sha256(verified).hexdigest()}", flush=True)
  finally:
    flash.close()

  activate(expected_product)


def main():
  parser = argparse.ArgumentParser(description="check and flash the bundled chestnut firmware")
  parser.add_argument("version", nargs="?", help="expected firmware version hash")
  parser.add_argument("--force", action="store_true", help="reflash even when the version matches")
  args = parser.parse_args()
  if os.geteuid() != 0:
    raise RuntimeError("flash.py must run as root")
  flash_chestnut(expected_version=args.version, force=args.force)


if __name__ == "__main__":
  try:
    main()
  except Exception as e:
    print(f"FAIL: {type(e).__name__}: {e}", file=sys.stderr)
    sys.exit(1)

View on GitHub (pinned to 516ec1e682)

Solutions

1. Re-run with sudo: sudo python flash.py [version] [--force]
2. In containers, run with --privileged or as root (docker exec -u 0 ...)
3. Verify with 'id -u' that the effective uid is 0 in the environment you are using

Example fix

# before
python openpilot/system/hardware/chestnut/flash.py

# after
sudo python openpilot/system/hardware/chestnut/flash.py

import os
if os.geteuid() != 0:
    raise SystemExit("flash.py requires root - re-run with sudo")

When it happens

Trigger: Running 'python flash.py' as a normal user; running inside a container whose default user is non-root; invoking via a wrapper/sudo -u that drops privileges.

Common situations: Forgetting sudo on a dev machine; CI containers running as uid != 1000-root; ssh sessions logged in as an unprivileged account.

Related errors

• could not disable USB runtime PM: {control}
• bundled firmware is {expected_product!r}, expected version {
• final full-image verification failed
• Unhandled sparse chunk type
• Raw hash mismatch '{raw_hash.hexdigest().lower()}'

AI-assisted analysis of commaai/openpilot@516ec1e682 (2026-08-15). Data as JSON: /api/errors/183ccd13a9357efc. Report an issue: GitHub.