Ashby 422 "invalid stage" when the agent moves a candidate to a renamed pipeline stage

Ashby 422 "invalid stage" when the agent moves a candidate to a renamed pipeline stage

TL;DR

The pipeline stage was renamed and the agent's hardcoded stage ID no longer exists. Resolve stages by name at runtime against the live pipeline, and fail with a clear message when the name is gone. Hardcoded stage IDs are a rename away from breaking.

422 Unprocessable Entity: "invalid stage" (Ashby, stage renamed)

Steps

1. List the job's current pipeline stages via the API. Expected: The renamed stage is visible with its new ID.

2. Update the agent to resolve stage names dynamically instead of hardcoding IDs. Expected: Renames stop breaking the workflow.

3. Re-run the failed moves against the resolved stage. Expected: Candidates move correctly.

4. Add a stage-resolution check that fails fast with the available stages when a name is missing. Expected: The error names the fix.

5. Subscribe to pipeline-change notifications if Ashby offers them, or re-resolve on a schedule. Expected: The mapping stays fresh.

When to use

• Ashby 422s with "invalid stage"
• a pipeline was renamed
• stages are hardcoded

When not to use

• the stage name is wrong (a typo, not a rename)
• the stage belongs to a different job's pipeline (check the job)
• the 422 is for a different field (read the message)

Tool compatibility

• Ashby API
• pipeline stage workflows

Variant phrasings

• "ashby 422 invalid stage"
• "ashby stage renamed"
• "ashby pipeline stage not found"

Why it happens

Pipelines get renamed as hiring processes evolve, and hardcoded stage IDs fossilize the old names. The 422 is Ashby refusing to move a candidate to a stage that no longer exists. Dynamic resolution costs one API call and survives every rename.

Edge cases

• stage names can collide across jobs; resolve per job, not globally
• renames sometimes split one stage into two; the mapping needs a human decision
• cache the resolution briefly; pipelines change rarely

Provenance

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