{"record":{"id":"183ccd13a9357efc","repo":"commaai/openpilot","slug":"flash-py-must-run-as-root","errorCode":null,"errorMessage":"flash.py must run as root","messagePattern":"flash\\.py must run as root","errorType":"console","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"openpilot/system/hardware/chestnut/flash.py","lineNumber":567,"sourceCode":"        program_sector(flash, addr, wanted)\n\n    verified = stable_read(flash, first_sector, span - first_sector, 3)\n    if verified != target:\n      raise RuntimeError(\"final full-image verification failed\")\n    print(f\"verified sha256={hashlib.sha256(verified).hexdigest()}\", flush=True)\n  finally:\n    flash.close()\n\n  activate(expected_product)\n\n\ndef main():\n  parser = argparse.ArgumentParser(description=\"check and flash the bundled chestnut firmware\")\n  parser.add_argument(\"version\", nargs=\"?\", help=\"expected firmware version hash\")\n  parser.add_argument(\"--force\", action=\"store_true\", help=\"reflash even when the version matches\")\n  args = parser.parse_args()\n  if os.geteuid() != 0:\n    raise RuntimeError(\"flash.py must run as root\")\n  flash_chestnut(expected_version=args.version, force=args.force)\n\n\nif __name__ == \"__main__\":\n  try:\n    main()\n  except Exception as e:\n    print(f\"FAIL: {type(e).__name__}: {e}\", file=sys.stderr)\n    sys.exit(1)\n","sourceCodeStart":549,"sourceCodeEnd":577,"githubUrl":"https://github.com/commaai/openpilot/blob/516ec1e68203439a73f340f1d0b3b91eabc626ee/openpilot/system/hardware/chestnut/flash.py#L549-L577","documentation":"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.","triggerScenarios":"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.","commonSituations":"Forgetting sudo on a dev machine; CI containers running as uid != 1000-root; ssh sessions logged in as an unprivileged account.","solutions":["Re-run with sudo: sudo python flash.py [version] [--force]","In containers, run with --privileged or as root (docker exec -u 0 ...)","Verify with 'id -u' that the effective uid is 0 in the environment you are using"],"exampleFix":"# before\npython openpilot/system/hardware/chestnut/flash.py\n\n# after\nsudo python openpilot/system/hardware/chestnut/flash.py","handlingStrategy":"validation","validationCode":"import os\nif os.geteuid() != 0:\n    raise SystemExit(\"flash.py requires root - re-run with sudo\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Wrap flash invocations in scripts that assert os.geteuid() == 0 first, so the failure is expected and immediate","In containers, standardize on 'docker exec -u 0' or USER root for flashing jobs"],"tags":["permissions","root","flashing","openpilot"],"backgroundTag":null,"analyzedSha":"516ec1e68203439a73f340f1d0b3b91eabc626ee","analyzedAt":"2026-08-15T00:17:37.461Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}