rust-lang/rust-clippy · error

changing this function will impact semver compatibility

Error message

changing this function will impact semver compatibility

What it means

A semver note attached to the needless_pass_by_ref_mut lint: the suggested change rewrites a parameter from &mut T to &T in a public function signature. Rust treats &mut T and &T as distinct types in the public API, so accepting the suggestion is a breaking change for external callers even though the function never used the parameter mutably. The note fires on publicly reachable items (subject to cfg/visibility) to warn before the fix is applied.

Solutions

  1. If the crate is pre-1.0 or a major bump is planned, accept the &mut -> &T change
  2. Otherwise suppress the lint on that item with #[allow(clippy::needless_pass_by_ref_mut)] and fix it at the next breaking release
  3. Audit external callers and published trait implementations that may reference the &mut signature before changing it
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at clippy_lints/src/needless_pass_by_ref_mut.rs:294 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rust-lang/rust-clippy@13aece1138 (2026-09-07). Data as JSON: /api/errors/616a373020631546. Report an issue: GitHub.

Appendix: source

Thrown at clippy_lints/src/needless_pass_by_ref_mut.rs:294

                        return;
                    };
                    let mut_span = after_mut_span.with_lo(after_mut_span.lo() - BytePos(3));
                    let is_cfged = is_cfged.get_or_insert_with(|| inherits_cfg(cx.tcx, *fn_def_id));
                    span_lint_hir_and_then(
                        cx,
                        NEEDLESS_PASS_BY_REF_MUT,
                        cx.tcx.local_def_id_to_hir_id(*fn_def_id),
                        sp,
                        "this parameter is a mutable reference but is not used mutably",
                        |diag| {
                            diag.span_suggestion(
                                mut_span,
                                "consider removing this `mut`",
                                "",
                                Applicability::Unspecified,
                            );
                            if cx.effective_visibilities.is_exported(*fn_def_id) {
                                diag.warn("changing this function will impact semver compatibility");
                            }
                            if *is_cfged {
                                diag.note("this is cfg-gated and may require further changes");
                            }
                        },
                    );
                }
            }
        }
    }
}

struct MutablyUsedVariablesCtxt<'tcx> {
    mutably_used_vars: HirIdSet,
    prev_bind: Option<HirId>,
    /// In async functions, the inner AST is composed of multiple layers until we reach the code
    /// defined by the user. Because of that, some variables are marked as mutably borrowed even
    /// though they're not. This field lists the `HirId` that should not be considered as mutable

View on GitHub (pinned to 13aece1138)