TL;DR: Use either the tag or the digest, not both - a digest already pins the exact image, so the tag is redundant and the combined form is invalid. Strip the tag and scan the digest-only reference. Fix the agent's reference builder so it emits one form or the other.

```text
invalid reference format
```

1. Print the exact reference string the agent constructed. Expected: you see the form `image:tag@sha256:...` with both a tag and a digest.
2. Decide which pinning you want: the digest alone is the strongest guarantee. Expected: you choose digest-only for immutable scans.
3. Re-run the scan with the digest-only reference. Expected: trivy accepts the reference and the scan starts.
4. Fix the agent's builder: when a digest is known, emit `image@sha256:...`; otherwise emit `image:tag`. Expected: newly constructed references never combine both.
5. Re-run the agent end to end. Expected: no more invalid-reference failures in the scan step.

## Use this when
- trivy rejects a reference containing both tag and digest
- an agent constructs image references programmatically
- pinning uses digests but a default tag sneaks in
- the error is exactly "invalid reference format"

## Not for this skill when
- the tag alone is invalid (typo or illegal characters)
- the digest alone is malformed
- the registry rejects a valid reference (an auth problem)
- the image simply does not exist

## Variant phrasings
- trivy invalid reference format tag digest
- image:tag@sha256 invalid
- docker reference tag and digest combined
- trivy digest reference rejected

## Why it happens
The container image reference grammar allows `name:tag` or `name@digest`, but not both - the tag becomes ambiguous once the digest pins the exact content. Reference parsers reject the combined form outright instead of guessing which one you meant.

## Edge cases
- some tools accept the combined form and silently ignore the tag - do not rely on that leniency
- trivy resolves digest-only references fine, but the output labels the target by digest - map it back to the tag in your reports
- agents that append a default `:latest` tag before adding a digest are the usual source - strip the default tag first
- registries that rewrite tags on push make tag-based scans drift - prefer digests for anything security-sensitive

## Provenance

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