## TL;DR
Rebuild the grouping from the current params location: DVC experiments stopped grouping by the params file after it was renamed, so update the grouping to read params from the new file and key, or group by the parameter values recorded in each experiment. Grouping keys are paths plus parameter names. A rename that the pipeline absorbed silently breaks every grouping built on the old path, while the experiments themselves are unharmed.

```text
agent failed to group DVC experiments by params file after params rename error join failure
```

## Use this when
- The check or run fails with this symptom: an agent fails to group DVC experiments by params file after a params rename and the join fails.
- You are working on an agent workflow grouping or joining DVC experiments by their parameters and the failure repeats on the same data or configuration.
- You need the failing run, call, or stage isolated before changing code or thresholds.

## Not for this skill when
- Experiments recorded before a parameter itself was renamed, which need a parameter mapping as well as a path update.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. List the params files and keys the stored experiments actually carry. Verify: old and new locations are both present across the history
2. Map the old path and key to the new one explicitly. Verify: every historical experiment resolves to the new grouping key
3. Regroup using the mapped keys, falling back to recorded parameter values where a file reference is missing. Verify: all experiments land in groups
4. Compare group counts against the experiment total. Verify: no experiment is dropped by the join
5. Record the rename mapping with the workflow. Verify: the next rename is an edit to the map, not a failure

## Variant phrasings
### agent failed group dvc experiments params file rename join
The shorter phrasing focused on the named failure.
### dvc experiments grouping params rename failure
The symptom phrasing a searcher tries next.
### dvc params rename grouping fix
The variant naming the failing stage or tool directly.

Compatibility: DVC experiments and params files, agent grouping and joining workflows

## Why it happens
DVC records parameters by the file and key they came from. Renaming params.yaml or moving it into a configuration directory is a routine refactor that leaves historical experiments pointing at a path that no longer exists, and any join or grouping on that path empties out.

## Edge cases / pitfalls
- Joins that drop rows silently are the danger; always reconcile counts before and after a grouping change.
- Parameter renames inside the file need the same mapping treatment as file renames.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_a4ojmxPzcUjFEvQn7t7KWA