{"record":{"id":"4a568fd048746cec","repo":"openmediavault/openmediavault","slug":"failed-to-get-list-of-unused-devices","errorCode":null,"errorMessage":"Failed to get list of unused devices.","messagePattern":"Failed to get list of unused devices\\.","errorType":"exception","errorClass":"OMV\\Exception","httpStatus":null,"severity":"error","filePath":"deb/openmediavault/usr/share/openmediavault/engined/rpc/filesystemmgmt.inc","lineNumber":597,"sourceCode":"     *   devicefile, size and description.\n     * @throw \\OMV\\Exception\n     */\n    public function getCandidates($params, $context)\n    {\n        // Validate the RPC caller context.\n        $this->validateMethodContext($context, [\n            \"role\" => OMV_ROLE_ADMINISTRATOR\n        ]);\n        // Get a list of all potential usable devices (excluding read-only devices).\n        $devs = \\OMV\\System\\Storage\\StorageDevice::enumerateUnusedObjects(\n            OMV_STORAGE_DEVICE_KIND_DEFAULT,\n            \\OMV\\LogicalOperator::ALL,\n            function (\\OMV\\System\\Storage\\StorageDeviceInterface $sd): bool {\n                return !$sd->isReadOnly();\n            }\n        );\n        if (false === $devs) {\n            throw new \\OMV\\Exception(\"Failed to get list of unused devices.\");\n        }\n        // Get a list of all detected file systems.\n        $filesystems = \\OMV\\System\\Filesystem\\Filesystem::getFilesystems();\n        // Get the list of device files that are occupied by a file system.\n        $usedDevs = [];\n        foreach ($filesystems as $filesystemk => $filesystemv) {\n            $usedDevs[] = $filesystemv->getParentDeviceFile();\n            // Check if the file system uses multiple devices, e.g.\n            // a BTRFS RAID, and add them.\n            if ($filesystemv->hasMultipleDevices()) {\n                $usedDevs = array_merge(\n                    $filesystemv->getDeviceFiles(),\n                    $usedDevs\n                );\n            }\n        }\n        $usedDevs = array_values(array_filter($usedDevs, \"strlen\"));\n        // Prepare the result list.","sourceCodeStart":579,"sourceCodeEnd":615,"githubUrl":"https://github.com/openmediavault/openmediavault/blob/dce610eb66f624c640d0eb7ce401ddd65b763520/deb/openmediavault/usr/share/openmediavault/engined/rpc/filesystemmgmt.inc#L579-L615","documentation":"Thrown by the unused-devices RPC when the storage device enumeration call (filtered to non-read-only devices) returns false instead of an array, meaning the underlying enumeration of storage devices failed entirely rather than merely returning an empty list. The boolean-false sentinel marks an internal enumeration error (e.g. command failures while probing disks).","triggerScenarios":"Calling rpc.filesystemmgmt.getUnusedDevices when \\OMV\\System\\Storage\\...::getDevices-style enumeration with the isReadOnly filter returns false — typically when blkid/lsblk/sysfs probing fails at the OS level.","commonSituations":"Broken /proc or /sys visibility in containers, missing or failing block-device tools, devices disappearing mid-scan (USB hot-unplug), or permissions/seccomp issues preventing the engined process from reading device information.","solutions":["Run the probing commands manually (lsblk, blkid) as the omv user to find which command fails, and repair it (reinstall util-linux/blkid, fix device nodes).","Check dmesg/journalctl for storage-layer errors (I/O errors, hot-unplug during scan) and rescan.","If running in a container, expose /sys, /proc and /dev block devices properly to the openmediavault-engined process.","Patch the RPC to return a partial/empty list or a structured error instead of a bare OMV\\Exception when enumeration fails, so the UI can distinguish 'no unused devices' from 'scan failed'."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"exec('lsblk --all --json 2>&1', $out, $rc);\nif (0 !== $rc) {\n    die(\"storage probing broken, fix lsblk/blkid before calling getUnusedDevices\\n\");\n}\n$this->rpc('FileSystemMgmt', 'getUnusedDevices', []);","typeGuard":"function storageEnumerationWorks(): bool {\n    exec('lsblk -d -n -o NAME 2>/dev/null', $out, $rc);\n    return 0 === $rc;\n}","tryCatchPattern":"try {\n    $devs = $this->rpc('FileSystemMgmt', 'getUnusedDevices', []);\n} catch (\\OMV\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Failed to get list of unused devices')) {\n        sleep(2); // transient device churn: retry after a short backoff\n        $devs = $this->rpc('FileSystemMgmt', 'getUnusedDevices', []);\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Ensure the omv user can read /sys, /proc and block device nodes (no restrictive containers/seccomp).","Avoid hot-unplugging devices during scans; debounce USB events before enumerating.","Keep util-linux/blkid installed and current on the system.","Monitor dmesg for storage I/O errors that would break device probing."],"tags":["php","storage","device-enumeration"],"backgroundTag":"empty-result-set","analyzedSha":"dce610eb66f624c640d0eb7ce401ddd65b763520","analyzedAt":"2026-09-15T09:48:09.960Z","contentChangedAt":"2026-09-15T09:48:09.960Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}