GoogleContainerTools/skaffold · error

PORT_FORWARD_RUN_GCLOUD_NOT_FOUND

PORT_FORWARD_RUN_GCLOUD_NOT_FOUND

Error message

gcloud not found

What it means

The Cloud Run port-forwarder (`runProxyForwarder.Start`) shells out to the `gcloud` CLI to create local proxy processes for Cloud Run services. Before starting any forward, it checks `gcloudInstalled()`; if the binary is not found on PATH it prints a message and returns this error with code PORT_FORWARD_RUN_GCLOUD_NOT_FOUND. No Cloud Run port-forwarding can be set up without gcloud.

Source

Thrown at pkg/skaffold/deploy/cloudrun/accessor.go:146

func (r *RunAccessor) Stop() {
	for _, forwarder := range r.forwarders {
		forwarder.Stop()
	}
}

func findGcloud() bool {
	cmd := exec.Command("gcloud", "--version")
	return cmd.Run() == nil
}

type runProxyForwarder struct {
	resources *resourceTracker
}

func (r *runProxyForwarder) Start(ctx context.Context, out io.Writer) error {
	if !gcloudInstalled() {
		output.Red.Fprintln(out, "gcloud not found on path. Unable to set up Cloud Run port forwarding")
		return sErrors.NewError(fmt.Errorf("gcloud not found"), &proto.ActionableErr{ErrCode: proto.StatusCode_PORT_FORWARD_RUN_GCLOUD_NOT_FOUND})
	}
	if r.resources.resources == nil {
		// no forwards configured
		return nil
	}
	for _, resource := range r.resources.resources {
		if resource.port == 0 {
			port := retrieveAvailablePort("localhost", 8080, r.resources.forwardedPorts)
			resource.port = port
		}
		if !resource.started {
			eventV2.TaskInProgress(constants.PortForward, "port forward URLs")
			// has not been started yet
			cctx, cancel := context.WithCancel(ctx)
			output.Yellow.Fprintf(out, "Forwarding service %s to local port %d\n", resource.name.String(), resource.port)
			cmd := exec.CommandContext(cctx, "gcloud", getGcloudProxyArgs(resource.name, resource.port)...)
			cmd.Stdout = out
			cmd.Stderr = out

View on GitHub (pinned to a1189de023)

Solutions

1. Install the Google Cloud SDK so `gcloud` is on PATH (https://cloud.google.com/sdk/docs/install)
2. Verify with `which gcloud` / `gcloud --version` in the same shell/environment where skaffold runs
3. If gcloud exists elsewhere, add its directory to PATH before launching skaffold (e.g. `export PATH=$PATH:/usr/local/google-cloud-sdk/bin`)
4. If you don't need Cloud Run port-forwarding, avoid the dev loop port-forward step for Cloud Run resources or use `skaffold run` instead of `skaffold dev`

Example fix

# before: skaffold dev fails with 'gcloud not found'
# after:
export PATH=$PATH:$HOME/google-cloud-sdk/bin
which gcloud && skaffold dev

if _, err := exec.LookPath("gcloud"); err != nil {
	return fmt.Errorf("gcloud CLI is required for Cloud Run port-forwarding: %w", err)
}

err := forwarder.Start(ctx, out)
if err != nil {
	var sErr *sErrors.Error
	if errors.As(err, &sErr) && sErr.Status().ErrCode == proto.StatusCode_PORT_FORWARD_RUN_GCLOUD_NOT_FOUND {
		fmt.Fprintln(os.Stderr, "Install the Google Cloud SDK: https://cloud.google.com/sdk/docs/install")
		os.Exit(1)
	}
	return err
}

When it happens

Trigger: `Start` is called during `skaffold dev`/`run` port-forwarding setup while a Cloud Run deployer is active, and `exec.LookPath("gcloud")` fails because the gcloud CLI is not installed or not on PATH for the process running skaffold.

Common situations: Fresh CI container or new machine without Google Cloud SDK; gcloud installed only for another user or in a venv not on PATH; running skaffold in a slim Docker build stage that lacks the SDK; PATH not sourced in the terminal/IDE launch environment.

Related errors

• PORT_FORWARD_RUN_PROXY_START_ERROR
• response must be a number, or empty
• skaffold apply called with both Cloud Run and Kubernetes dep
• INIT_CLOUD_RUN_LOCATION_ERROR
• DEPLOY_GET_CLOUD_RUN_CLIENT_ERR

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