What causes "create device path: {folder_path} failed" in FoundationAgents/MetaGPT?

Verify `adb shell mkdir -p` succeeds manually on the target device; fix whatever it reports (PATH, permissions, stale connection).

FoundationAgents/MetaGPT · error · RuntimeError

create device path: {folder_path} failed

Error message

create device path: {folder_path} failed

What it means

AndroidExtEnv.create_device_path runs `adb shell mkdir <folder> -p` through execute_adb_with_cmd, which returns the ADB_EXEC_FAIL sentinel when the subprocess exits non-zero. If the mkdir fails, the constructor raises RuntimeError 'create device path: {folder_path} failed', meaning the adb command itself could not run or was rejected by the device.

Source

Thrown at metagpt/environment/android/android_ext_env.py:149

    @property
    def adb_prefix(self):
        """adb cmd prefix with `device_id`"""
        return f"adb -s {self.device_id} "

    def execute_adb_with_cmd(self, adb_cmd: str) -> str:
        adb_cmd = adb_cmd.replace("\\", "/")
        res = subprocess.run(adb_cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
        exec_res = ADB_EXEC_FAIL
        if not res.returncode:
            exec_res = res.stdout.strip()
        return exec_res

    def create_device_path(self, folder_path: Path):
        adb_cmd = f"{self.adb_prefix_shell} mkdir {folder_path} -p"
        res = self.execute_adb_with_cmd(adb_cmd)
        if res == ADB_EXEC_FAIL:
            raise RuntimeError(f"create device path: {folder_path} failed")

    @property
    def device_shape(self) -> tuple[int, int]:
        adb_cmd = f"{self.adb_prefix_shell} wm size"
        shape = (0, 0)
        shape_res = self.execute_adb_with_cmd(adb_cmd)
        if shape_res != ADB_EXEC_FAIL:
            shape = tuple(map(int, shape_res.split(": ")[1].split("x")))
        return shape

    def list_devices(self):
        adb_cmd = "adb devices"
        res = self.execute_adb_with_cmd(adb_cmd)
        devices = []
        if res != ADB_EXEC_FAIL:
            devices = res.split("\n")[1:]
            devices = [device.split()[0] for device in devices]
        return devices

View on GitHub (pinned to 11cdf466d0)

Solutions

Verify `adb shell mkdir <path> -p` succeeds manually on the target device; fix whatever it reports (PATH, permissions, stale connection).
Ensure adb is installed and resolvable from the Python process environment.
Reconnect/restart the device or emulator, then re-construct the environment.
If the default dirs are unwritable on your ROM, pass screenshot_dir/xml_dir values pointing to a writable location like /sdcard/... if the API allows overriding them.

Example fix

# before
env = AndroidExtEnv(device_id="emulator-5554")  # RuntimeError: create device path: ... failed

# after
# shell: verify manually first
#   adb -s emulator-5554 shell mkdir /sdcard/metagpt/screenshot -p
#   adb -s emulator-5554 shell mkdir /sdcard/metagpt/xml -p
env = AndroidExtEnv(device_id="emulator-5554")

Defensive patterns

Strategy: try-catch

Validate before calling

def adb_mkdir_ok(env, folder) -> bool:
    return env.execute_adb_with_cmd(f"{env.adb_prefix_shell} mkdir {folder} -p") != ADB_EXEC_FAIL

# probe before relying on construction to succeed:
assert adb_mkdir_ok(env, env.screenshot_dir), f"cannot create {env.screenshot_dir} on device"

Try / catch

try:
    env = AndroidExtEnv(device_id=serial)
except RuntimeError as e:
    if "create device path" in str(e):
        raise SystemExit("adb mkdir failed: check adb on PATH, device connected, and path writability") from e
    raise

Prevention

Pre-flight the exact adb command manually (`adb -s <serial> shell mkdir <dir> -p`) to confirm it returns 0.
Ensure adb is on PATH for the Python process, especially in CI containers.
Keep the device connection stable during construction — re-run if the emulator restarts mid-init.

When it happens

Trigger: Constructing AndroidExtEnv (it creates screenshot_dir and xml_dir on the device) when adb is not on PATH (subprocess returncode != 0), the device serial became stale between list_devices and mkdir, or the target path is on a read-only/unwritable volume.

Common situations: adb missing from PATH in a container/CI; device disconnected or emulator killed mid-init; shell quoting issues with the adb_prefix_shell string; running on Windows where the backslash replacement in execute_adb_with_cmd interacts badly with paths.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/2b24ebdfdfd0f5d7. Report an issue: GitHub.