INSPECT_BUILD_ENV_ALREADY_EXISTS_ERR

INSPECT_BUILD_ENV_ALREADY_EXISTS_ERR

Error message

trying to create a %q build environment definition that already exists, in file %s (or, with profile: trying to create a %q build environment definition that already exists, in profile %q in file %s)

What it means

BuildEnvAlreadyExists is returned by the skaffold inspect 'add build env' API (AddClusterBuildEnv, AddGcbBuildEnv, AddLocalBuildEnv) when a build environment of the requested type already exists in the target skaffold.yaml file, or within the given profile. It carries code INSPECT_BUILD_ENV_ALREADY_EXISTS_ERR and a suggestion to use modify or a new profile instead of adding a duplicate.

Source

Thrown at pkg/skaffold/inspect/errors.go:35

package inspect

import (
	"errors"
	"fmt"

	sErrors "github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/errors"
	"github.com/GoogleContainerTools/skaffold/v2/proto/v1"
)

// BuildEnvAlreadyExists specifies that there's an existing build environment definition for the same type.
func BuildEnvAlreadyExists(b BuildEnv, filename string, profile string) error {
	var msg string
	if profile == "" {
		msg = fmt.Sprintf("trying to create a %q build environment definition that already exists, in file %s", b, filename)
	} else {
		msg = fmt.Sprintf("trying to create a %q build environment definition that already exists, in profile %q in file %s", b, profile, filename)
	}
	return sErrors.NewError(errors.New(msg),
		&proto.ActionableErr{
			Message: msg,
			ErrCode: proto.StatusCode_INSPECT_BUILD_ENV_ALREADY_EXISTS_ERR,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_INSPECT_USE_MODIFY_OR_NEW_PROFILE,
					Action:         "Use the `modify` command instead of the `add` command to overwrite fields for an already existing build environment type. Otherwise pass the `--profile` flag with a unique name to create the new build environment definition in a new profile instead",
				},
			},
		})
}

// BuildEnvNotFound specifies that the target build environment definition doesn't exist.
func BuildEnvNotFound(b BuildEnv, filename string, profile string) error {
	var msg string
	if profile == "" {
		msg = fmt.Sprintf("trying to modify a %q build environment definition that doesn't exist, in file %s", b, filename)
	} else {

View on GitHub (pinned to a1189de023)

Solutions

Use `skaffold inspect modify build-env` instead of add to update the existing definition
Target a new or different profile so the add is not a duplicate
Inspect the current state first (`skaffold inspect build-envs --filename ... [--profile ...]`) and remove the duplicate if unwanted
Make scripts idempotent: check existence before calling add

Example fix

// before
skaffold inspect add build-env --type cluster --filename skaffold.yaml  # already exists
// after
skaffold inspect modify build-env --type cluster \
  --namespace new-ns --filename skaffold.yaml
# or add into a fresh profile:
skaffold inspect add build-env --type cluster \
  --profile ci --filename skaffold.yaml

Defensive patterns

Strategy: validation

Validate before calling

envs, err := inspect.ListBuildEnvs(filename, profile)
if err == nil {
    for _, e := range envs {
        if e.Type == "cluster" {
            return errors.New("cluster build env already exists; use modify instead of add")
        }
    }
}

Try / catch

err := skaffoldInspect("add", "build-env", "--type", "cluster")
if err != nil && strings.Contains(err.Error(), "already exists") {
    // fall back to modify
    err = skaffoldInspect("modify", "build-env", "--type", "cluster")
}

Prevention

Check existing build-envs with `skaffold inspect build-envs` before adding
Make provisioning scripts idempotent (add only if type absent)
Target distinct profiles per environment definition

When it happens

Trigger: Calling a build-env add mutation (e.g. via `skaffold inspect add build-env` or the inspect API) targeting a file/profile that already contains a build env of the same type, while the mutation only allows one definition per type.

Common situations: Rerunning an automation script that adds a build env without idempotency; target file already configured with the same builder type; adding to a profile that inherits or defines the same env; pointing --filename at the wrong file.

Related errors

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/0d7e8b5bf5506485. Report an issue: GitHub.