kubernetes/kops · error

cannot parse VFS path %q: %v

Error message

cannot parse VFS path %q: %v

What it means

AddS3Permissions returns this when vfs.Context.BuildVfsPath cannot parse one of the cluster's state-store root URLs into a vfs.Path. VFS paths must use a scheme kOps recognizes (s3://, file://, memfs://, etc.); a malformed or unknown URL makes IAM S3 statement generation impossible for that root.

Source

Thrown at pkg/model/iam/iam_builder.go:597

					klog.V(4).Infof("Ignoring location %q because found parent %q", l, locations[j])
					isTopLevel = false
				}
			}
			if isTopLevel {
				klog.V(4).Infof("Found root location %q", l)
				roots = append(roots, l)
			}
		}
	}

	sort.Strings(roots)

	s3Buckets := sets.NewString()

	for _, root := range roots {
		vfsPath, err := vfs.Context.BuildVfsPath(root)
		if err != nil {
			return fmt.Errorf("cannot parse VFS path %q: %v", root, err)
		}

		switch path := vfsPath.(type) {
		case *vfs.S3Path:
			iamS3Path := path.Bucket() + "/" + path.Key()
			iamS3Path = strings.TrimSuffix(iamS3Path, "/")

			s3Buckets.Insert(path.Bucket())

			if err := b.buildS3GetStatements(p, iamS3Path); err != nil {
				return err
			}

		case *vfs.MemFSPath:
			// Tests - we emulate the s3 permissions so that we can get an idea of the full policy

			iamS3Path := "placeholder-read-bucket/" + path.Location()
			b.buildS3GetStatements(p, iamS3Path)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Run the failing store string through `kops get clusters --state <url>` to see whether kOps can parse it.
2. Fix the URL syntax (double slash after scheme, valid bucket name) in spec.configStore.base or the --state flag.
3. Ensure the VFS backend for the scheme is supported in this build (e.g. only s3/file/memfs for AWS IAM generation).
4. Trim whitespace and shell-escape the --state value; verify with `kops toolbox dump` or re-run update.

Example fix

// before
base: "s3:my-bucket/clusters/example.k8s.local" // no // after scheme -> parse fails
// after
base: "s3://my-bucket/clusters/example.k8s.local"

if _, err := vfs.Context.BuildVfsPath(root); err != nil {
    return fmt.Errorf("state store %q is not a valid VFS path", root)
}
if !strings.HasPrefix(root, "s3://") {
    return fmt.Errorf("AWS clusters require an s3:// state store, got %q", root)
}

err := builder.AddS3Permissions(policy)
if err != nil {
    if strings.Contains(err.Error(), "cannot parse VFS path") {
        // prompt user to fix --state / configStore.base
    }
    return err
}

When it happens

Trigger: Any PolicyBuilder.AddS3Permissions call where a root derived from spec.configStore.base (or legacy ClusterName state location) is not a valid VFS path — e.g. empty scheme, unsupported protocol, or malformed bucket/key syntax passed to BuildVfsPath.

Common situations: Typo in the state store URL (s3:/bucket instead of s3://bucket); scheme for a VFS backend not compiled into the AWS context; leading/trailing whitespace or shell mangling of the --state flag; config hand-edited with an invalid base URL.

Related errors

• path is not cluster readable: %v
• failed to generate AWS IAM S3 access statements: %v
• unknown writeable path, can't apply IAM policy: %q
• building VFS path for %q: %w
• invalid s3 path: %q

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