GoogleContainerTools/skaffold · error

cannot parse the name template on user defined port forwarde

Error message

cannot parse the name template on user defined port forwarder: %w

What it means

applyWithTemplate expands the resource Name template of a user-defined port-forward entry via util.ExpandEnvTemplateOrFail. Malformed template syntax or a missing environment variable produces this wrapped error. Start aborts preparation of that port-forward resource.

Source

Thrown at pkg/skaffold/kubernetes/portforward/resource_forwarder.go:121

			return fmt.Errorf("retrieving services for automatic port forwarding: %w", err)
		}
		serviceResources = found
	}
	p.portForwardResources(ctx, append(p.userDefinedResources, serviceResources...))
	return nil
}

func applyWithTemplate(resource *latest.PortForwardResource) error {
	if resource.Namespace != "" {
		namespace, err := util.ExpandEnvTemplateOrFail(resource.Namespace, nil)
		if err != nil {
			return fmt.Errorf("cannot parse the namespace template on user defined port forwarder: %w", err)
		}
		resource.Namespace = namespace
	}
	name, err := util.ExpandEnvTemplateOrFail(resource.Name, nil)
	if err != nil {
		return fmt.Errorf("cannot parse the name template on user defined port forwarder: %w", err)
	}
	resource.Name = name
	return nil
}

func (p *ResourceForwarder) Stop() {
	p.entryManager.Stop()
}

// Port forward each resource individually in a goroutine
func (p *ResourceForwarder) portForwardResources(ctx context.Context, resources []*latest.PortForwardResource) {
	var wg sync.WaitGroup
	for _, r := range resources {
		wg.Add(1)
		go func(r latest.PortForwardResource) {
			defer wg.Done()
			p.portForwardResource(ctx, r)
		}(*r)

View on GitHub (pinned to a1189de023)

Solutions

1. Correct the template syntax in the portForward resourceName field
2. Export the referenced environment variable before invoking skaffold
3. Replace the template with a literal resource name
4. Lint skaffold.yaml template expressions against documented util.ExpandEnvTemplateOrFail rules

Example fix

# before (skaffold.yaml)
portForward:
  - resourceType: pod
    resourceName: "{{.SERVICE}"
# after
portForward:
  - resourceType: pod
    resourceName: "{{.SERVICE_NAME}}"  # with SERVICE_NAME exported in the environment

func validNameTemplate(name string) error {
    if name == "" {
        return fmt.Errorf("portForward resourceName is empty")
    }
    if strings.Count(name, "{{") != strings.Count(name, "}}") {
        return fmt.Errorf("unbalanced template braces in resourceName %q", name)
    }
    return nil
}

if err := applyWithTemplate(res); err != nil {
    if strings.Contains(err.Error(), "name template") {
        return fmt.Errorf("fix portForward.resourceName in skaffold.yaml: %v", err)
    }
    return err
}

When it happens

Trigger: util.ExpandEnvTemplateOrFail(resource.Name, nil) fails in applyWithTemplate (called from Start) when the portForward resourceName in skaffold.yaml contains invalid template syntax or references an unset env var.

Common situations: resourceName written as {{.POD_NAME} (missing brace) or referencing an env var absent in CI; using os.Expand-style $VAR syntax where Go templates are expected; typos in field names.

Related errors

• cannot parse the namespace template on user defined port for
• cannot parse the release namespace template: %w
• bucket name is empty
• INSPECT_PROFILE_NOT_FOUND_ERR
• cannot resolve active Kubernetes context - multiple contexts

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