kubernetes/kops · error

unknown / unhandled path type: %q

Error message

unknown / unhandled path type: %q

What it means

BuildVfsPath maps a path string to a VFS Path implementation by prefix matching known schemes (file, s3, do, linode, hos, memfs, gs, k8s, swift, azureblob, scw). A path with "://" whose scheme matches none of these has no implementation, so the library rejects it.

Source

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

	}

	if strings.HasPrefix(p, "k8s://") {
		return c.buildKubernetesPath(p)
	}

	if strings.HasPrefix(p, "swift://") {
		return c.buildOpenstackSwiftPath(p)
	}

	if strings.HasPrefix(p, "azureblob://") {
		return c.buildAzureBlobPath(p)
	}

	if strings.HasPrefix(p, "scw://") {
		return c.buildSCWPath(p)
	}

	return nil, fmt.Errorf("unknown / unhandled path type: %q", p)
}

// readAWSMetadata reads the specified path from the AWS EC2 metadata service
func (c *VFSContext) readAWSMetadata(ctx context.Context, path string) ([]byte, error) {
	config, err := awsconfig.LoadDefaultConfig(ctx)
	if err != nil {
		return nil, fmt.Errorf("failed to load AWS config: %w", err)
	}

	client := imds.NewFromConfig(config)

	if strings.HasPrefix(path, "/meta-data/") {
		s, err := client.GetMetadata(ctx, &imds.GetMetadataInput{
			Path: strings.TrimPrefix(path, "/meta-data/"),
		})
		if err != nil {
			return nil, fmt.Errorf("error reading from AWS metadata service: %v", err)
		}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use a supported scheme prefix: file://, s3://, gs://, do://, linode://, hos://, memfs://, k8s://, swift://, azureblob://, scw://
2. Fix typos in the scheme (e.g. azureblob:// not azure://, hos:// not hetzner://)
3. Check `kops` docs/version - unsupported backends require a different storage location
4. If the string is really a local path, remove the accidental '://' from it

Example fix

// before
export KOPS_STATE_STORE=azure://mystorage/clusters
// after
export KOPS_STATE_STORE=azureblob://mystorageaccount/mystorage

var supportedSchemes = []string{"file", "s3", "do", "linode", "hos", "memfs", "gs", "k8s", "swift", "azureblob", "scw"}
func validateVfsScheme(p string) error {
	i := strings.Index(p, "://")
	if i < 0 {
		return nil
	}
	scheme := p[:i]
	for _, s := range supportedSchemes {
		if scheme == s {
			return nil
		}
	}
	return fmt.Errorf("scheme %q not supported by vfs; use one of %v", scheme, supportedSchemes)
}

func isSupportedVfsPath(p string) bool {
	for _, s := range []string{"file://", "s3://", "do://", "linode://", "hos://", "memfs://", "gs://", "k8s://", "swift://", "azureblob://", "scw://"} {
		if strings.HasPrefix(p, s) {
			return true
		}
	}
	return !strings.Contains(p, "://")
}

path, err := vfs.Context.BuildVfsPath(p)
if err != nil && strings.Contains(err.Error(), "unknown / unhandled path type") {
	return fmt.Errorf("KOPS_STATE_STORE scheme not supported: %w", err)
}

When it happens

Trigger: Calling BuildVfsPath (via ConfigBase, NewServer, parseFlags, transferFile, validateServiceAccountIssuerDiscovery, ResolveS3Region) with an unknown scheme, e.g. 'azblob://container/key', 'oss://bucket/key', 'abfs://...', or a typo like 's403://bucket'.

Common situations: Setting KOPS_STATE_STORE to a cloud kOps does not support (or a misspelled scheme); using an aliased or renamed scheme from an older kOps version; pointing tooling at an object store with a similar-but-different URL scheme.

Related errors

• parsing path for kops-channels manifest %s: %w
• building VFS path for %q: %w
• unhandled type %T
• error parsing configStore.base %q: %v
• expected azureblob:// ConfigStore.Base for Azure cluster, go

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