What causes "invalid bucket path: %q" in kubernetes/kops?

Correct the scw:// URL so it is a valid URL (no invalid % escapes or control characters).

invalid bucket path: %q

Error message

invalid bucket path: %q

What it means

buildSCWPath validates that the given path parses as a URL and carries the scw scheme. This error is thrown when url.Parse fails on the string, meaning the path is malformed and cannot be interpreted as a bucket URL.

Source

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

	if err != nil {
		return nil, err
	}
	if c.azureClients == nil {
		c.azureClients = make(map[string]*azblob.Client)
	}
	c.azureClients[account] = client
	return client, nil
}

func (c *VFSContext) buildSCWPath(p string) (*S3Path, error) {
	endpoint := os.Getenv("S3_ENDPOINT")
	if endpoint == "" {
		return nil, fmt.Errorf("required S3_ENDPOINT env var for path: %q", p)
	}

	u, err := url.Parse(p)
	if err != nil {
		return nil, fmt.Errorf("invalid bucket path: %q", p)
	}
	if u.Scheme != "scw" {
		return nil, fmt.Errorf("invalid bucket path: %q", p)
	}

	bucket := strings.TrimSuffix(u.Host, "/")
	if bucket == "" {
		return nil, fmt.Errorf("invalid bucket 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
}

View on GitHub (pinned to 4c8573c808)

Solutions

Correct the scw:// URL so it is a valid URL (no invalid % escapes or control characters).
Echo the state store value and re-enter it manually to eliminate invisible characters from copy-paste.
Quote the value in the shell to prevent glob/escape expansion (e.g. export KOPS_STATE_STORE='scw://bucket').

Example fix

// before
BuildVfsPath("scw://my%zzbucket/state") // invalid percent-escape
// after
BuildVfsPath("scw://my-bucket/state")

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

func isParseableURL(p string) bool {
    _, err := url.Parse(p)
    return err == nil
}

Try / catch

if _, err := ctx.BuildVfsPath(p); err != nil && strings.Contains(err.Error(), "invalid bucket path") {
    return fmt.Errorf("check the state store URL for typos/invalid escapes: %w", err)
}

Prevention

Quote state store values in shell to avoid escape/glob expansion.
Re-type the URL manually if it was copy-pasted with unknown characters.
Keep bucket names URL-safe (lowercase letters, digits, hyphens).

When it happens

Trigger: Calling BuildVfsPath with a string registered for the scw handler that url.Parse rejects — e.g. contains control characters, invalid percent-escapes like "%zz", or is otherwise not a valid URL.

Common situations: Copy-pasted state store values with stray whitespace/control characters, shell-expanded variables containing invalid escape sequences, or typos that corrupt the URL.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

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