What causes "`--edges public` requires `-Zunstable-options`" in rust-lang/cargo?

Run on nightly and pass `-Zunstable-options`, e.g. `cargo +nightly tree -Zunstable-options -e public`.

`--edges public` requires `-Zunstable-options`

Error message

`--edges public` requires `-Zunstable-options`

What it means

`cargo tree --edges public` exposes the dependency graph's public surface, but that edge kind is gated behind `-Zunstable-options`. parse_edge_kinds (tree.rs:306-308) checks `gctx.cli_unstable().unstable_options` and bails with this message when the `public` edge was requested on stable.

Source

Thrown at src/bin/cargo/commands/tree.rs:307

                            true
                        }
                    })
                    .collect()
            },
        );

        if args.flag("no-dev-dependencies") {
            gctx.shell()
                .warn("the --no-dev-dependencies flag has changed to -e=no-dev")?;
            kinds.push("no-dev");
        }

        if kinds.is_empty() {
            kinds.extend(&["normal", "build", "dev"]);
        }

        if public && !gctx.cli_unstable().unstable_options {
            anyhow::bail!("`--edges public` requires `-Zunstable-options`");
        }

        (kinds, no_proc_macro, public)
    };

    let mut result = HashSet::default();
    let insert_defaults = |result: &mut HashSet<EdgeKind>| {
        result.insert(EdgeKind::Dep(DepKind::Normal));
        result.insert(EdgeKind::Dep(DepKind::Build));
        result.insert(EdgeKind::Dep(DepKind::Development));
    };
    if kinds.iter().any(|k| k.starts_with("no-")) {
        insert_defaults(&mut result);
        for kind in &kinds {
            match *kind {
                "no-normal" => result.remove(&EdgeKind::Dep(DepKind::Normal)),
                "no-build" => result.remove(&EdgeKind::Dep(DepKind::Build)),
                "no-dev" => result.remove(&EdgeKind::Dep(DepKind::Development)),

View on GitHub (pinned to 0e07a15537)

Solutions

Run on nightly and pass `-Zunstable-options`, e.g. `cargo +nightly tree -Zunstable-options -e public`.
If you must stay on stable, omit `public` from `--edges`.
Pin the CI toolchain to nightly where this feature is used.

Example fix

// before
$ cargo tree -e public
error: `--edges public` requires `-Zunstable-options`

// after
$ cargo +nightly tree -Zunstable-options -e public

Defensive patterns

Strategy: validation

Validate before calling

let needs_public = edges.iter().any(|e| e == "public");
if needs_public && !nightly_with_z_unstable_options {
    return Err("--edges public requires nightly + -Zunstable-options".into());
}

Type guard

fn requires_unstable(edges: &[String]) -> bool {
    edges.iter().any(|e| e == "public")
}

Prevention

Use rust-toolchain.toml to pin nightly where unstable tree edges are used.
Gate unstable flags behind a feature flag in build scripts.

When it happens

Trigger: Running `cargo tree -e public` (or `--edges public`) without passing `-Zunstable-options` on a nightly toolchain.

Common situations: Following nightly-only documentation on stable; CI pinned to stable that uses the public-edge feature; scripts written against nightly run on stable.

Related errors

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/eb404e69db01c4eb.json. Report an issue: GitHub.