Hmbown/CodeWhale · error · ValidationError

could not read Cargo metadata

Error message

could not read Cargo metadata: {error}

What it means

scripts/release/validate-crate-publish-order.py loads Cargo workspace metadata, either from a provided file or by invoking cargo metadata. This ValidationError wraps an OSError raised while reading the user-supplied metadata file, so the exact filesystem failure (missing file, permissions, etc.) is surfaced as a validation error.

Solutions

  1. Verify the metadata file path exists and is a regular file (ls -l <path>)
  2. Regenerate the file with cargo metadata --locked --format-version 1 --no-deps > metadata.json
  3. Run the validator from the directory where the relative path resolves, or pass an absolute path
  4. Check file permissions if the file exists but cannot be read

Example fix

# before
python scripts/release/validate-crate-publish-order.py meta.json
# after
python scripts/release/validate-crate-publish-order.py ./cargo-metadata.json  # verified existing path
Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
p = Path(metadata_file)
if not p.is_file():
    raise SystemExit(f"metadata file not found: {p.resolve()}")
if not os.access(p, os.R_OK):
    raise SystemExit(f"metadata file not readable: {p}")

Try / catch

try:
    result = subprocess.run(["python", "scripts/release/validate-crate-publish-order.py", str(path)], check=False)
except ValidationError as e:
    if str(e).startswith("could not read Cargo metadata"):
        print("regenerate with: cargo metadata --locked --format-version 1 --no-deps > cargo-metadata.json")

Prevention

When it happens

Trigger: Calling load_metadata with a metadata_file Path that does not exist, is a directory, or is unreadable due to permissions, causing read_text to raise OSError.

Common situations: Typoed path to a saved cargo metadata JSON; passing a path relative to the wrong working directory in CI; a prior pipeline step that was supposed to dump cargo metadata output failed silently, leaving no file; read-only or restrictive permissions on the artifact.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/5d00aed1800450c5. Report an issue: GitHub.

Appendix: source

Thrown at scripts/release/validate-crate-publish-order.py:37


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--metadata-file",
        type=Path,
        help="Read Cargo metadata from this file instead of invoking cargo (tests only).",
    )
    parser.add_argument("crates", nargs="+", help="Maintained publication order")
    return parser.parse_args()


def load_metadata(metadata_file: Path | None) -> dict[str, Any]:
    if metadata_file is not None:
        try:
            raw = metadata_file.read_text(encoding="utf-8")
        except OSError as error:
            raise ValidationError(f"could not read Cargo metadata: {error}") from error
    else:
        process = subprocess.run(
            ["cargo", "metadata", "--locked", "--format-version", "1", "--no-deps"],
            check=False,
            capture_output=True,
            text=True,
        )
        if process.returncode != 0:
            detail = process.stderr.strip()
            suffix = f": {detail}" if detail else ""
            raise ValidationError(
                f"cargo metadata failed with exit code {process.returncode}{suffix}"
            )
        raw = process.stdout

    try:
        metadata = json.loads(raw)
    except json.JSONDecodeError as error:

View on GitHub (pinned to 433685b202)