error checking if configuration file %s exists already: %v

Error message

error checking if configuration file %s exists already: %v

What it means

writeConfig in VFSClientBase checks whether a configuration file already exists before honoring vfs.WriteOptionOnlyIfExists. When ReadFile fails with a non-NotExist error, the library cannot determine existence and wraps the underlying vfs error with this message. It signals a state-store access problem (permissions, network, backend failure), not a missing file.

Source

Thrown at pkg/client/simple/vfsclientset/commonvfs.go:151

func (c *VFSClientBase) writeConfig(ctx context.Context, cluster *kops.Cluster, configPath vfs.Path, o runtime.Object, writeOptions ...vfs.WriteOption) error {
	data, err := c.serialize(o)
	if err != nil {
		return fmt.Errorf("error marshaling object: %v", err)
	}

	create := false
	for _, writeOption := range writeOptions {
		switch writeOption {
		case vfs.WriteOptionCreate:
			create = true
		case vfs.WriteOptionOnlyIfExists:
			_, err = configPath.ReadFile(ctx)
			if err != nil {
				if os.IsNotExist(err) {
					return fmt.Errorf("cannot update configuration file %s: does not exist", configPath)
				}
				return fmt.Errorf("error checking if configuration file %s exists already: %v", configPath, err)
			}
		default:
			return fmt.Errorf("unknown write option: %q", writeOption)
		}
	}

	acl, err := acls.GetACL(ctx, configPath, cluster)
	if err != nil {
		return err
	}

	rs := bytes.NewReader(data)
	if create {
		err = configPath.CreateFile(ctx, rs, acl)
	} else {
		err = configPath.WriteFile(ctx, rs, acl)
	}
	if err != nil {

View on GitHub (pinned to 4c8573c808)

Solutions

Verify the state store backend is reachable and credentials are valid (e.g. aws s3 ls on the bucket).
Check the exact inner %v error to identify the vfs backend failure and fix it.
Confirm the --state / KOPS_STATE_STORE URL is correct and the bucket exists in the expected region.
Retry after resolving transient network issues.

Example fix

// before
KOPS_STATE_STORE=s3://wrong-bucket kops update cluster
// after
aws s3 ls s3://my-correct-bucket  # verify access first
KOPS_STATE_STORE=s3://my-correct-bucket kops update cluster

Defensive patterns

Strategy: try-catch

Validate before calling

_, err := store.ReadFile(ctx, path)
if err != nil && !os.IsNotExist(err) {
    return fmt.Errorf("state store not readable: %w", err)
}

Try / catch

if err := updateCluster(cfg); err != nil {
    if strings.Contains(err.Error(), "error checking if configuration file") {
        // inspect wrapped cause, verify credentials/bucket, retry
    }
}

Prevention

Validate cloud credentials before kops operations
Verify KOPS_STATE_STORE points at an existing, accessible bucket
Preflight state-store access with a simple read before writes

When it happens

Trigger: Calling Create or Update (which call writeConfig with vfs.WriteOptionOnlyIfExists) while the state-store backend is unreachable, permission-denied, or otherwise fails ReadFile with an error that is not os.ErrNotExist.

Common situations: S3/GCS credentials missing or expired, state-store bucket deleted or region mismatched, network outage during `kops update cluster` or `kops create`, VFS ACL misconfiguration.

Related errors

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