What causes "building vfs path: %w" in kubernetes/kops?

Read the wrapped cause — it names the invalid path/scheme.

building vfs path: %w

Error message

building vfs path: %w

What it means

When remapping nodeup script additional files, each source URI under remapPrefix is resolved via vfsContext.BuildVfsPath. If the URI is not a valid/parseable VFS path (bad scheme, malformed path), BuildVfsPath errors and it is wrapped as 'building vfs path: %w'. The file is never read.

Source

Thrown at pkg/commands/toolbox_enroll.go:877

	// If this is the control plane, we want to copy the config from s3/gcs to the local file system on the target node,
	// so that we don't need credentials to the state store.
	if bootConfig.InstanceGroupRole.HasControlPlane() {
		remapPrefix := "s3://" // TODO: Support GCS?

		// targetDir is the location of the config on the target node.
		targetDir := "/etc/kubernetes/kops/config"

		// remapFile remaps a file from s3/gcs etc to the local file system on the target node.
		remapFile := func(pSrc *string, destDir string) error {
			src := *pSrc
			if !strings.HasPrefix(src, remapPrefix) {
				return nil
			}

			srcPath, err := vfsContext.BuildVfsPath(src)
			if err != nil {
				return fmt.Errorf("building vfs path: %w", err)
			}
			b, err := srcPath.ReadFile(ctx)
			if err != nil {
				return fmt.Errorf("reading file: %w", err)
			}

			dest := strings.TrimPrefix(src, remapPrefix)
			dest = path.Join(destDir, dest)
			bootstrapData.NodeupScriptAdditionalFiles[dest] = b

			*pSrc = dest
			return nil
		}

		// remapTree remaps a file tree from s3/gcs etc to the local file system on the target node.
		remapTree := func(pSrc *string, dest string) error {
			src := *pSrc
			if !strings.HasPrefix(src, remapPrefix) {

View on GitHub (pinned to 4c8573c808)

Solutions

Read the wrapped cause — it names the invalid path/scheme.
Correct the source URI scheme and path (must match a supported VFS backend: s3://, gs://, file://, etc.).
Verify the path exists and is spelled exactly (bucket, prefix).
Test with `kops toolbox template`/dry-run to confirm the path resolves before running enroll.

Example fix

// before
nodeup script additional file: src="s3:/bucket/files/conf.yaml"   // malformed scheme
// after
src="s3://bucket/files/conf.yaml"

Defensive patterns

Strategy: validation

Validate before calling

// Validate the additional-file source URI scheme/path before use
u, err := url.Parse(src)
if err != nil || (u.Scheme != "s3" && u.Scheme != "gs" && u.Scheme != "file" && u.Scheme != "memfs") {
	return fmt.Errorf("unsupported additional-file source %q", src)
}

Try / catch

if err != nil {
	if strings.Contains(err.Error(), "building vfs path") {
		return fmt.Errorf("check additional-file URI scheme/path: %w", err)
	}
	return err
}

Prevention

Use canonical VFS URIs (s3://bucket/key) — never single-slash forms
Lint nodeup script additionalFiles entries before applying
Match the VFS scheme to a backend compiled into your kops binary

When it happens

Trigger: A nodeup script additional-file source string with an unsupported VFS scheme or malformed URI (e.g. typo'd s3:// path, missing bucket, unsupported file:// form) is processed by the remap closure in GetBootstrapData/RunToolboxEnroll.

Common situations: Hand-written kopsBootScript nodeup script additional files with wrong paths; state store scheme mismatch (memfs vs s3) in tests or dry-runs; URL containing characters VFS cannot parse.

Related errors

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/e90e2bf14b87ac2a. Report an issue: GitHub.