rust-lang/cargo · error

subcommand is required, but `{alias_name}` is empty

Error message

subcommand is required, but `{alias_name}` is empty

What it means

In aliased_command (main.rs:154-160), Cargo resolves a `cargo <command>` alias from config (`alias.<command>`). If the resolved alias value is an empty list/string, the alias points nowhere, so Cargo cannot determine which subcommand to run and bails.

Source

Thrown at src/bin/cargo/main.rs:159

            record
                .val
                .split_whitespace()
                .map(|s| s.to_string())
                .collect(),
        ),
        Ok(None) => None,
        Err(_) => gctx.get::<Option<Vec<String>>>(&alias_name)?,
    };

    let result = user_alias.or_else(|| {
        builtin_aliases_execs(command).map(|command_str| vec![command_str.1.to_string()])
    });
    if result
        .as_ref()
        .map(|alias| alias.is_empty())
        .unwrap_or_default()
    {
        anyhow::bail!("subcommand is required, but `{alias_name}` is empty");
    }
    Ok(result)
}

/// List all runnable commands
fn list_commands(gctx: &GlobalContext) -> BTreeMap<String, CommandInfo> {
    let mut commands = third_party_subcommands(gctx);

    for cmd in commands::builtin() {
        commands.insert(
            cmd.get_name().to_string(),
            CommandInfo::BuiltIn {
                about: cmd.get_about().map(|s| s.to_string()),
            },
        );
    }

    // Add the builtin_aliases and them descriptions to the

View on GitHub (pinned to 0e07a15537)

Solutions

1. Edit `.cargo/config.toml` (or `~/.cargo/config.toml`) and give the alias a real command, e.g. `[alias]\nt = "test"`.
2. Remove the empty alias entry if it is unused.
3. Run `cargo config get` (or inspect the file) to confirm the alias value.

Example fix

// before (.cargo/config.toml)
[alias]
r = ""

// after
[alias]
r = "run"

// Validate config alias before relying on it
let alias = gctx.get_string(&format!("alias.{cmd}"))?;
if let Some(rec) = alias {
    if rec.val.trim().is_empty() {
        return Err(format!("alias.{cmd} is empty; set a real command"));
    }
}

fn alias_is_valid(v: &str) -> bool {
    !v.trim().is_empty()
}

When it happens

Trigger: Defining `[alias] foo = ""` or `foo = []` in `.cargo/config.toml` and then running `cargo foo`. Also triggered by a builtin alias that resolves empty.

Common situations: Misconfigured `~/.cargo/config.toml` or `.cargo/config.toml` with an empty alias; environment-variable expansion producing empty; copy-pasted config with a placeholder that was never filled in.

Related errors

• subcommand is required, add a subcommand to the command alia
• alias {} has unresolvable recursive definition: {} -> {}
• argument for --color must be auto, always, or never, but fou
• invalid character `+` in dependency name: `+{toolchain}`
• feature `{feature}` must be qualified by the dependency it's

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