{"record":{"id":"5da95bdffd605572","repo":"hacksider/Deep-Live-Cam","slug":"failed-to-open-camera","errorCode":null,"errorMessage":"Failed to open camera","messagePattern":"Failed to open camera","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"modules/video_capture.py","lineNumber":80,"sourceCode":"                    (self.device_index, cv2.CAP_MSMF),\n                    (self.device_index, cv2.CAP_ANY),\n                ]\n\n                for dev_id, backend in capture_methods:\n                    try:\n                        self.cap = cv2.VideoCapture(dev_id, backend, open_params)\n                        if self.cap.isOpened():\n                            break\n                        self.cap.release()\n                    except Exception:\n                        continue\n            elif platform.system() == \"Linux\":\n                self.cap = cv2.VideoCapture(f\"/dev/video{self.device_index}\")\n            else:\n                self.cap = cv2.VideoCapture(self.device_index)\n\n            if not self.cap or not self.cap.isOpened():\n                raise RuntimeError(\"Failed to open camera\")\n\n            # Belt-and-braces: also set via cap.set() for backends that honor\n            # post-open changes (MSMF, V4L2). DSHOW ignores these, but the\n            # construction params above already handled it.\n            if platform.system() != \"Windows\":\n                self.cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*'MJPG'))\n                self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, width)\n                self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, height)\n                self.cap.set(cv2.CAP_PROP_FPS, fps)\n\n            # Read back resolution (usually reliable)\n            self.actual_width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))\n            self.actual_height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))\n\n            # CAP_PROP_FPS is unreliable on DirectShow — often reports 30\n            # even when the camera delivers 60.  Measure empirically by\n            # timing a burst of frames.\n            reported_fps = self.cap.get(cv2.CAP_PROP_FPS)","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/hacksider/Deep-Live-Cam/blob/987f6b392b1740623b3fa8a5cb46fdd0b7e185b9/modules/video_capture.py#L62-L98","documentation":"RuntimeError raised in VideoCapture.start (modules/video_capture.py) when every backend attempt fails to open the device: on Windows each (device id, backend, params) combination threw or failed isOpened; on Linux cv2.VideoCapture('/dev/video<N>') failed; on other platforms the default-open failed. It means OpenCV could not obtain a capture handle at all — the device is busy, absent, permission-denied, or not supported by the backend used.","triggerScenarios":"Device already occupied by another process (Zoom/OBS/browser using the webcam, or a previous run that didn't release()); on Linux, /dev/videoN missing (wrong index — many cameras register multiple /dev/video nodes and only some capture), udev permission denied (user not in the video group), or the camera is a metadata-only node; on Windows, DSHOW/MSMF backend mismatch with the driver; headless machines with no camera at all; passing a device_index that passed construction-time checks but went invalid before start().","commonSituations":"Linux permission issues (no rw on /dev/video*); index confusion from multiple /dev/video nodes per UVC camera; another app holding the camera exclusively; camera suspended by USB autosuspend; Snap/Flatpak packaging lacking device access; CI/headless runs where /dev/video doesn't exist.","solutions":["Confirm nothing else holds the camera (close other conferencing/recording apps; kill stale processes) and retry.","On Linux: check the node exists and you have access — ls -l /dev/video*, add user to the video group (sudo usermod -aG video $USER, re-login), and verify with v4l2-ctl --list-devices that you target a capture-capable node, not a metadata node.","Verify the index/enumeration again right before start() (device may have disconnected after construction) and prefer selecting by device name.","For packaging (Snap/Flatpak/Docker), grant camera device access or run outside the sandbox; in Docker map /dev/video* into the container.","If all else fails, test the camera outside the app (e.g. cv2.VideoCapture(0) in a REPL, or cheese/guvcview) to isolate app vs system."],"exampleFix":"# before\ncap = VideoCapture(device_index=0)\nif not cap.start():\n    pass  # error swallowed, later frames fail confusingly\n\n# after\ncap = VideoCapture(device_index=0)\ntry:\n    cap.start()\nexcept RuntimeError as e:\n    print(f\"Camera unavailable: {e}; is another app using it?\")\n    # fall back to a file source or exit cleanly","handlingStrategy":"fallback","validationCode":"# Linux: confirm the node exists, is capture-capable, and is readable/writable\nimport os, subprocess\nnode = f\"/dev/video{device_index}\"\nif not os.path.exists(node):\n    raise SystemExit(f\"{node} does not exist; list nodes with: v4l2-ctl --list-devices\")\nif not os.access(node, os.R_OK | os.W_OK):\n    raise SystemExit(f\"No permission on {node}; add user to 'video' group and re-login\")","typeGuard":null,"tryCatchPattern":"try:\n    cap.start()\nexcept RuntimeError as e:\n    if \"Failed to open camera\" in str(e):\n        # device busy/absent: retry once after releasing, else fall back to file input\n        cap = None\n        source = fallback_video_path  # e.g. a recorded clip for testing\n    else:\n        raise","preventionTips":["Always call cap.release()/destroy the object on shutdown so the camera isn't left held.","Close other apps using the webcam (meetings, OBS, browser tabs) before starting capture.","On Linux, target the capture-capable /dev/video node (v4l2-ctl --list-devices) — UVC cameras expose several nodes.","Grant device access in sandboxed packaging (Snap/Flatpak/Docker --device).","Disable USB autosuspend for external webcams that drop out intermittently."],"tags":["python","opencv","camera","device-busy","linux","windows","permissions"],"backgroundTag":null,"analyzedSha":"987f6b392b1740623b3fa8a5cb46fdd0b7e185b9","analyzedAt":"2026-08-14T19:48:25.860Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}