## TL;DR
Fix the step image reference, because the registry does not hold what the step asks for: the Valohai step names an environment image that is missing in the registry, so correct the image name or tag in the step, or build and push the image under that exact reference. Valohai pulls the step environment image by its full reference at execution start. A renamed image, a pruned tag, or a registry move all present as the same not found, and no step code runs until the image resolves.

```text
Valohai execution failed error "step environment image not found in registry"
```

## Use this when
- The check or run fails with this symptom: a Valohai execution fails with step environment image not found in registry.
- You are working on a Valohai project whose steps specify Docker environment images 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
- An image that exists in a different registry the execution environment cannot reach, which needs the image mirrored or the registry access granted.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Read the step definition for the exact image reference, including the tag or digest. Verify: the requested reference is known character for character
2. List the images and tags in the registry the execution pulls from. Verify: the reference is absent, or present under a different tag
3. Either push the intended image under the requested reference, or update the step to the reference that exists. Verify: the registry now satisfies the step request
4. Run a minimal execution of the step. Verify: the image pulls and the step starts
5. Pin step images by digest or a protected tag so pruning cannot remove them silently. Verify: the reference survives registry cleanup

## Variant phrasings
### valohai step environment image not found in registry
The shorter phrasing focused on the named failure.
### valohai execution failed image not found error
The symptom phrasing a searcher tries next.
### valohai step image reference fix
The variant naming the failing stage or tool directly.

Compatibility: Valohai steps and environment images, container registry tag management

## Why it happens
Step definitions outlive the images they name: registries prune old tags, teams rename images during migrations, and a reference copied between projects points at a registry the step never had. The execution fails at image pull, before any project code is involved.

## Edge cases / pitfalls
- A floating tag that was overwritten can also produce a wrong image rather than a missing one; digest pinning prevents both failures.
- Check registry credentials when an image appears missing; private images report as not found to unauthenticated pulls.

## Provenance

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