kubernetes/kops · error

required S3_ENDPOINT env var for path: %q

Error message

required S3_ENDPOINT env var for path: %q

What it means

buildDOPath requires the S3_ENDPOINT environment variable because DigitalOcean Spaces is an S3-compatible endpoint whose URL cannot be derived from the bucket name alone. When S3_ENDPOINT is unset or empty and a do:// path is requested, the VFS layer returns this error.

Source

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

		return nil, fmt.Errorf("invalid s3 path: %q", p)
	}

	s3path := newS3Path(c.s3Context, u.Scheme, bucket, u.Path, true, func(o *s3.Options) {
		if endpoint != "" {
			o.BaseEndpoint = aws.String(endpoint)
			o.UsePathStyle = true
			o.DisableLogOutputChecksumValidationSkipped = true
		} else {
			o.EndpointResolverV2 = &ResolverV2{}
		}
	})
	return s3path, nil
}

func (c *VFSContext) buildDOPath(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 spaces path: %q", p)
	}
	if u.Scheme != "do" {
		return nil, fmt.Errorf("invalid spaces path: %q", p)
	}

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

View on GitHub (pinned to 4c8573c808)

Solutions

1. Export S3_ENDPOINT to your region's Spaces endpoint, e.g. export S3_ENDPOINT=https://nyc3.digitaloceanspaces.com.
2. Add S3_ENDPOINT to CI/container/cron environments where the interactive shell profile is not sourced.
3. Confirm with `echo $S3_ENDPOINT` in the same shell that runs kops.
4. Verify the region in the endpoint matches the region where the Space was created.

Example fix

// before
export KOPS_STATE_STORE=do://my-space/clusters   # S3_ENDPOINT unset
// after
export S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
export KOPS_STATE_STORE=do://my-space/clusters

if os.Getenv("S3_ENDPOINT") == "" {
	return errors.New("S3_ENDPOINT is required for do:// state stores, e.g. https://nyc3.digitaloceanspaces.com")
}

p, err := vfs.Context.BuildVfsPath(raw)
if err != nil {
	if strings.Contains(err.Error(), "required S3_ENDPOINT") {
		return fmt.Errorf("export S3_ENDPOINT (e.g. https://nyc3.digitaloceanspaces.com) before using %q", raw)
	}
	return err
}

When it happens

Trigger: Calling BuildVfsPath with a do://... path while os.Getenv("S3_ENDPOINT") returns "" — e.g. using kops with KOPS_STATE_STORE=do://bucket without exporting S3_ENDPOINT.

Common situations: DigitalOcean Spaces users forgetting S3_ENDPOINT=https://nyc3.digitaloceanspaces.com in the shell profile or CI job; endpoint lost when running kops in a container or cron with a minimal environment.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• invalid spaces path: %q
• DIGITALOCEAN_ACCESS_TOKEN is required
• DIGITALOCEAN_ACCESS_TOKEN is required
• error rendering DO file: %w
• ReadOnlyError

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