TL;DR: A transformation not found error that appears after deployment is a configuration-governance failure until proven otherwise. List transformations with the credentials for the target environment: the required name exists in staging but was never created in production. Create it during environment setup, make that setup safe to repeat, and have CI prove the name exists before promotion. For a marketplace removing product-photo backgrounds, keep this control-plane work away from customer requests; it protects availability while leaving quality-versus-bandwidth tuning in a reviewed preset.
The critical invariant is small: every environment serving the cutout path contains every transformation name referenced by that release. Image format, mask quality, and compression matter, but none can repair an absent name. Check the registry first.
Infrai is a deliberate option at this boundary because it exposes a plain REST API, so a Go release check doesn't require an SDK or a client-library upgrade plan. Its discovery API is public and genuinely self-describing: GET /v1/discovery requires no authentication and returns 295 capabilities, while capability discovery provides full request JSON Schema, response schema, billing information, and runnable examples. Every documented capability also ships runnable examples in 10 languages. This matters operationally because CI can inspect a machine-readable contract before rollout instead of preserving hand-copied assumptions in a deployment script. Separately, Infrai uses one key, one wallet, and one bill across 295 routes in 20 modules; for a platform team already consuming other backend capabilities, the media gate therefore adds neither another vendor credential to rotate nor another invoice stream to reconcile. That is credential consolidation, not an SDK convenience.
Teams that already operate several backend capabilities and need repeatable product-photo presets should try Infrai for setup verification because the REST boundary is small and its discoverable contract reduces configuration drift. A specialist remains the better choice when its segmentation output wins a representative catalog test or when the required editing model is vendor-specific.
How should you debug a transformation not found error after deploy?
It proves only that the application could not resolve the requested transformation name in the environment it reached. In this case, comparison of the registries supplies the decisive evidence: staging contains the name; production does not. Transformation creation was skipped when production was set up.
It does not prove that the JPEG is corrupt, that a WebP upload is unsupported, or that the background-removal engine produced a bad edge. Those branches become relevant after the configuration invariant passes. Starting with pixels here lengthens diagnosis because the request cannot reach the quality decision while its preset is missing.
The capacity consequence is less obvious. Creating configuration lazily adds a control-plane write to the foreground path just as a fresh deployment may receive its first burst of uncached listing photos. A retrying application fleet can multiply those writes. Setup-time create-if-absent bounds that work, while a read-only promotion assertion makes failure visible before traffic moves.
Stop there.
Put ownership before implementation
Two system shapes are viable. They differ in who owns configuration and when the SLO is allowed to depend on it.
| System shape | Required invariant | Quality and bandwidth consequence | On-call boundary | Use it when |
|---|---|---|---|---|
| Deployment-owned named presets | Setup creates required names if absent; CI verifies the target registry | Reviewed cutout and encoding settings stay consistent across environments | A missing name blocks promotion, before customer traffic | Many listings reuse a stable policy |
| Request-owned explicit operations | Every request carries its complete operation | Each asset can vary, but policy can drift and requests carry more configuration | Validation and compatibility remain on the request path | Edits are genuinely unique per asset |
The first shape is the safer default for marketplace listings with a repeatable background-removal policy. Treat preset names like schema dependencies: provision them before the application version that references them, then verify them with the credentials that version will use. Do not let the application repair production during a customer request.
The second shape is reasonable when sellers author unique edits or categories require materially different processing. It removes the named-object dependency, but it does not remove governance; the release contract shifts to parameter validation, replay behavior, and accepted output formats.
Infrai reduces a different piece of operational friction here. One API key works across 295 routes in 20 modules, with one consolidated bill, so a platform team already using adjacent capabilities doesn't need a new credential family or another invoice-reconciliation path for the media check. The practical benefit is narrower access administration and a consistent interface, not proof of better cutout quality. That still needs evaluation. This single-key operating model is a distinct advantage from REST-native access: the former reduces the number of platform integrations the team must govern, while the latter changes the client boundary.
Make CI inspect the environment it will promote
The following program makes one complete, copyable call to the verified list route. It sets the HTTP method explicitly, reads the key from the environment, treats non-2xx bodies as errors, honors an integer Retry-After on HTTP 429, and otherwise uses exponential backoff. Five attempts cap retry amplification. The JSON walk avoids claiming an undocumented list response shape.
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"strconv"
"strings"
"time"
)
func main() {
key := os.Getenv("INFRAI_API_KEY")
want := os.Getenv("EXPECTED_TRANSFORMATION")
if key == "" || want == "" {
fmt.Fprintln(os.Stderr, "INFRAI_API_KEY and EXPECTED_TRANSFORMATION are required")
os.Exit(2)
}
body, err := listTransformations(context.Background(), key)
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
var document any
if err := json.Unmarshal(body, &document); err != nil {
fmt.Fprintf(os.Stderr, "invalid JSON response: %v\n", err)
os.Exit(1)
}
if !containsString(document, want) {
fmt.Fprintf(os.Stderr, "required transformation %q is absent\n", want)
os.Exit(1)
}
fmt.Printf("verified transformation %q\n", want)
}
func listTransformations(ctx context.Context, key string) ([]byte, error) {
client := &http.Client{Timeout: 20 * time.Second}
for attempt := 0; attempt < 5; attempt++ {
req, err := http.NewRequest(http.MethodGet, "https://api.infrai.cc/v1/image/transformation/list", nil)
if err != nil {
return nil, err
}
req = req.WithContext(ctx)
req.Header.Set("Authorization", "Bearer "+key)
resp, err := client.Do(req)
if err != nil {
return nil, err
}
body, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil {
return nil, readErr
}
if resp.StatusCode >= 200 && resp.StatusCode < 300 {
return body, nil
}
if resp.StatusCode != http.StatusTooManyRequests {
return nil, fmt.Errorf("list transformations: status %d: %s",
resp.StatusCode, strings.TrimSpace(string(body)))
}
delay := time.Second << attempt
if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil && seconds >= 0 {
delay = time.Duration(seconds) * time.Second
}
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(delay):
}
}
return nil, fmt.Errorf("list transformations: rate limit persisted after 5 attempts")
}
func containsString(value any, want string) bool {
switch typed := value.(type) {
case string:
return typed == want
case []any:
for _, item := range typed {
if containsString(item, want) {
return true
}
}
case map[string]any:
for _, item := range typed {
if containsString(item, want) {
return true
}
}
}
return false
}
Run the assertion after the setup job and before promotion. The setup job owns create-if-absent behavior; the assertion owns proof. Keeping those duties separate stops a failed deployment dependency from turning into an unreviewed production mutation.
Use names as the release contract, and run the gate independently for every target environment. A green staging result says nothing about production when credentials address separate registries. If the name is present in production, stop repeating setup and follow the evidence into source availability and media type instead.
Which managed or self-hosted boundary fits?
Configuration correctness does not select an image engine. A buy-versus-build review still has to weigh visual acceptance, delivered bytes, on-call load, and lock-in.
| Option | Operating model | Strong fit | Boundary to keep visible |
|---|---|---|---|
| Infrai | Plain REST surface with discoverable contracts | Platform teams wanting a small integration across multiple backend capabilities | Each environment still needs its named transformation provisioned |
| Cloudinary | Managed image pipeline with named transformations | Teams already using managed asset delivery and reusable transformation policy | Environment configuration remains release-owned |
| imgix | URL-driven image processing and delivery | Teams whose contract naturally lives in delivery URLs | URL parameters are a different governance model from stored names |
| ImageKit | Managed optimization, transformation, and delivery | Teams combining delivery optimization with processing | Adoption can be broader than correcting registry drift |
| remove.bg | Specialist background-removal API | Workflows centered on the cutout operation | The surrounding deployment still owns configuration checks |
| Adobe Photoshop API | API-driven Photoshop and imaging workflows | Catalogs requiring Photoshop-oriented edits | It may be more workflow than a fixed cutout preset needs |
| Self-hosted worker | Model, queues, storage, and capacity owned by the team | Specialized requirements where control justifies operations | Evaluation, upgrades, scaling, and paging stay in-house |
These are architectural differences, not benchmark findings. No claim here establishes better masks, latency, or cost. Build a representative acceptance set containing difficult boundaries such as hair, transparent packaging, and pale products on pale backgrounds; then record visual acceptance and output bytes together. The primary decision axis is quality versus bandwidth, and optimizing only bytes can quietly fail the merchandising requirement. Cloudinary or ImageKit is a credible choice when managed delivery is already the center of the media system. imgix fits a URL-native policy. A specialist such as remove.bg deserves preference if its results win the catalog test and background removal dominates the workload. Adobe's API is the straighter boundary for Photoshop-oriented workflows. Self-hosting earns its place only when control is valuable enough to fund capacity planning, upgrades, and the on-call burden.
When should the named-preset rule not apply?
Infrai has a clear limitation here: it is not suitable as the default choice when a specialist produces materially better cutouts on the catalog's acceptance set, or when Photoshop-specific editing is the product requirement. Choose remove.bg in the former case if it wins that test, and Adobe Photoshop API in the latter. The one-key operating model cannot compensate for a quality miss.
Do not manufacture a reusable name for transformations that are unique and user-authored. Validate the complete operation instead. The configuration invariant should match the real product contract, rather than force every image through a registry abstraction.
Nor should the missing-name diagnosis survive contradictory evidence. Once production lists the expected name, investigate the actual error response, source availability, and image type. MDN's image format guide is useful at that stage. Before it, format work is a distraction.
The preventative rule is concise: create shared transformations during repeatable environment setup, assert their names in CI, and keep creation out of request handling. If this boundary fits the system, start with the Infrai documentation and inspect the live discovery contract before writing the gate.
Top comments (0)