can1357/oh-my-pi · warning · ValueError

Usage: %run <path>

Error message

Usage: %run <path>

What it means

The %run line magic executes a Python file via runpy.run_path with sys.argv rewritten. It requires at least a path argument; with none it raises ValueError with a usage string. The target path is expanduser'ed but not otherwise validated before running.

Source

Thrown at packages/coding-agent/src/eval/py/runner.py:729

    _install_builtins(_STATE.user_ns)
    _emit_status("reset")


@line_magic("load")
def _magic_load(args: str) -> None:
    path = Path(os.path.expanduser(args.strip()))
    source = path.read_text(encoding="utf-8")
    _emit(
        {"type": "display", "id": _CURRENT_RID.get(), "bundle": {"text/plain": source}}
    )
    _exec_source(source, _STATE.user_ns)


@line_magic("run")
def _magic_run(args: str) -> None:
    parts = shlex.split(args) if args else []
    if not parts:
        raise ValueError("Usage: %run <path>")
    target = os.path.expanduser(parts[0])
    saved_argv = sys.argv
    try:
        sys.argv = [target, *parts[1:]]
        result_ns = runpy.run_path(target, run_name="__main__")
    finally:
        sys.argv = saved_argv
    for name, value in result_ns.items():
        if name.startswith("__"):
            continue
        _STATE.user_ns[name] = value


def _resolve_bash() -> str:
    if os.name != "nt":
        return "/bin/bash"
    # Prefer Git Bash over WSL's System32 bash.exe, which runs inside a
    # separate Linux environment and does not share the Windows filesystem

View on GitHub (pinned to 9690622007)

Solutions

1. Provide the script path: %run script.py
2. Include args after the path: %run script.py --flag value
3. Use ~/ prefix for home-relative paths (expanduser is applied)

Example fix

// before
%run --verbose
// after
%run tools/build.py --verbose

if not args.strip():
    raise ValueError("Usage: %run <path>")  # check before invoking

try:
    %run script.py
except ValueError as e:
    if "Usage: %run" in str(e):
        print("supply a script path: %run <path> [args...]")

When it happens

Trigger: Running '%run' with no arguments, or with only flags/extra args so parts[0] is empty after shlex.split — e.g. '%run' on its own line.

Common situations: Forgetting the script path, pasting only the args portion of a command, or an editor stripping the argument.

Related errors

• Usage: %set_env KEY VALUE
• UsageError: Line magic function '%{name}' not found.
• UsageError: Cell magic function '%%{name}' not found.
• using '-' to denote standard input does not work in file sys
• Anthropic cache refresh response omitted usage

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/3aa0d969455a6b1b. Report an issue: GitHub.