credential-alias ` ` (defined in ` `) will be ignored…

Error message

credential-alias `{name}` (defined in `{}`) will be ignored because it would shadow a built-in credential-provider

What it means

When resolving a credential provider, if the provider path names a built-in provider (e.g. `cargo:token`, `cargo:macos-keychain`) and the user has also defined a `credential-alias.<name>` entry, the alias would shadow the built-in. Cargo ignores the alias and emits this warning, reporting which config file defined it, and keeps using the built-in provider.

Solutions

Rename the alias in the config file named in the warning (the `defined in` part) to something that does not collide with a built-in provider name.
If you intended custom behavior, point the provider list at the alias's new name instead of the built-in provider name.
Remove the credential-alias entry entirely if the built-in provider already does what you want.

Example fix

// before: ~/.cargo/config.toml
[credential-alias]
"cargo" = ["!", "my-login"]

// after: ~/.cargo/config.toml
[credential-alias]
"my-login" = ["!", "my-login"]

Defensive patterns

Strategy: validation

Validate before calling

# ensure no credential-alias shadows a built-in (anything starting with 'cargo:')
awk -F= '/\[credential-alias\]/{f=1;next} /^\[/{f=0} f{print}' ~/.cargo/config.toml \
  | tr -d '" ' | cut -d= -f1 | grep -E '^cargo(:|$)' && echo 'alias shadows built-in'

Try / catch

// warning is advisory; surface it when wiring providers programmatically
if stderr.contains("will be ignored because it would shadow a built-in") {
    // rename the alias and reconfigure
}

Prevention

Name custom credential aliases distinctly from built-in providers (avoid names starting with `cargo`).
Keep [credential-alias] definitions in one config scope and review them when changing global-credential-providers.
Read cargo's startup warnings after editing credential config — shadowing is silent otherwise.

When it happens

Trigger: Calling resolve_credential_alias via credential_provider when the resolved provider has no args, its path matches a name in BUILT_IN_PROVIDERS, and gctx.get(["credential-alias", name]) successfully resolves an alias definition from config (e.g. [credential-alias] "cargo" = ["!", ...]).

Common situations: Users defining [credential-alias] entries named like built-in providers (`cargo`, `cargo:token`) by mistake; config copied from examples that named an alias the same as a built-in; combining custom providers with the global-credential-providers defaults.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-09-22). Data as JSON: /api/errors/986ec41907f7146b. Report an issue: GitHub.

Appendix: source

Thrown at src/util/auth/mod.rs:231

    if let Some(name) = &name {
        tracing::debug!("found alternative registry name `{name}` for {sid}");
        gctx.get::<Option<RegistryConfig>>(["registries", name.as_str()])
    } else {
        tracing::debug!("no registry name found for {sid}");
        Ok(None)
    }
}

/// Use the `[credential-alias]` table to see if the provider name has been aliased.
fn resolve_credential_alias(gctx: &GlobalContext, mut provider: PathAndArgs) -> Vec<String> {
    if provider.args.is_empty() {
        let name = provider.path.raw_value();
        let key = format!("credential-alias.{name}");
        if let Ok(alias) = gctx.get::<Value<PathAndArgs>>(["credential-alias", name]) {
            tracing::debug!("resolving credential alias '{key}' -> '{alias:?}'");
            if BUILT_IN_PROVIDERS.contains(&name) {
                let _ = gctx.shell().warn(format!(
                    "credential-alias `{name}` (defined in `{}`) will be \
                    ignored because it would shadow a built-in credential-provider",
                    alias.definition
                ));
            } else {
                provider = alias.val;
            }
        }
    }
    provider.args.insert(
        0,
        provider
            .path
            .resolve_program(gctx)
            .to_str()
            .unwrap()
            .to_string(),
    );

View on GitHub (pinned to 98a09e7e7d)