kubernetes/kops · error

invalid kubernetes vfs path: %q

Error message

invalid kubernetes vfs path: %q

What it means

buildKubernetesPath converts 'k8s://' VFS paths into a KubernetesPath served through the in-cluster k8s context. If the raw string cannot be parsed by url.Parse, kOps cannot construct the path and throws this error before checking the scheme or bucket.

Source

Thrown at util/pkg/vfs/context.go:459

	}

	bucket := strings.TrimSuffix(u.Host, "/")
	if bucket == "" {
		return nil, fmt.Errorf("invalid Hetzner object storage path: %q", p)
	}

	s3path := newS3Path(c.s3Context, u.Scheme, bucket, u.Path, false, func(o *s3.Options) {
		o.BaseEndpoint = aws.String(endpoint)
		o.UsePathStyle = true
		o.DisableLogOutputChecksumValidationSkipped = true
	})
	return s3path, nil
}

func (c *VFSContext) buildKubernetesPath(p string) (*KubernetesPath, error) {
	u, err := url.Parse(p)
	if err != nil {
		return nil, fmt.Errorf("invalid kubernetes vfs path: %q", p)
	}
	if u.Scheme != "k8s" {
		return nil, fmt.Errorf("invalid kubernetes vfs path: %q", p)
	}

	bucket := strings.TrimSuffix(u.Host, "/")
	if bucket == "" {
		return nil, fmt.Errorf("invalid kubernetes vfs path: %q", p)
	}

	k8sPath := newKubernetesPath(c.k8sContext, bucket, u.Path)
	return k8sPath, nil
}

func (c *VFSContext) buildMemFSPath(p string) (*MemFSPath, error) {
	if !strings.HasPrefix(p, "memfs://") {
		return nil, fmt.Errorf("memfs path not recognized: %q", p)
	}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Rewrite the path in canonical form k8s://<bucket-or-context>/<key> with valid percent-encoding
2. Check KOPS_STATE_STORE / the --state-store flag for stray characters or truncated values
3. URL-encode any special characters in keys (%20 for spaces, etc.)

Example fix

// before (invalid escape)
k8s://bucket/%zz/key
// after
k8s://bucket/key

if _, err := url.Parse(stateStore); err != nil {
	return fmt.Errorf("kubernetes vfs path %q is not a valid URL: %w", stateStore, err)
}

p, err := vfs.Context.BuildVfsPath(stateStore)
if err != nil {
	if strings.Contains(err.Error(), "invalid kubernetes vfs path") {
		return fmt.Errorf("state store %q failed URL parsing; use k8s://<bucket>/<key>", stateStore)
	}
	return err
}

When it happens

Trigger: BuildVfsPath dispatches to buildKubernetesPath and url.Parse(p) returns an error for the given path string (e.g. malformed percent-escapes like k8s://bucket/%zz or control characters in the path).

Common situations: A k8s:// state store value assembled by a script with unescaped special characters; an invalid percent-encoding sequence pasted into the path; a corrupted config value in KOPS_STATE_STORE.

Related errors

• error parsing ConfigStore.Base %q: %v
• error parsing locationStore=%q: %w
• parsing etcd backup-store %q: %w
• parsing configStore.base %q: %w
• cannot parse VFS path %q: %v

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