hashicorp/terraform · error

failed to open file at %v: %v

Error message

failed to open file at %v: %v

What it means

Raised by remoteClient.getObject() (cos/client.go:186) on the very first guard: the COS HTTP response pointer is nil. A nil response means the request never produced an HTTP reply - the underlying cos-go-sdk returned an error before any status code, e.g. network/DNS failure or an unconfigured client.

Source

Thrown at internal/backend/remote-state/cos/client.go:186

		return nil, fmt.Errorf("lock file %s not exists", c.lockFile)
	}

	info := &statemgr.LockInfo{}
	if err := json.Unmarshal(data, info); err != nil {
		return nil, err
	}

	info.ID = checksum

	return info, nil
}

// getObject get remote object
func (c *remoteClient) getObject(cosFile string) (exists bool, data []byte, checksum string, err error) {
	rsp, err := c.cosClient.Object.Get(c.cosContext, cosFile, nil)
	if rsp == nil {
		log.Printf("[DEBUG] getObject %s: error: %v", cosFile, err)
		err = fmt.Errorf("failed to open file at %v: %v", cosFile, err)
		return
	}
	defer rsp.Body.Close()

	log.Printf("[DEBUG] getObject %s: code: %d, error: %v", cosFile, rsp.StatusCode, err)
	if err != nil {
		if rsp.StatusCode == 404 {
			err = nil
		} else {
			err = fmt.Errorf("failed to open file at %v: %v", cosFile, err)
		}
		return
	}

	checksum = rsp.Header.Get("X-Cos-Meta-Md5")
	log.Printf("[DEBUG] getObject %s: checksum: %s", cosFile, checksum)
	if len(checksum) != 32 {
		err = fmt.Errorf("failed to open file at %v: checksum %s invalid", cosFile, checksum)

View on GitHub (pinned to c9def3e214)

Solutions

1. Verify network connectivity and DNS resolution to the COS endpoint from the host.
2. Confirm bucket name and region are correct and the COS URL resolves.
3. Ensure secret_id/secret_key (or STS token / CAM role) are configured so the client initializes.
4. Check the endpoint/accelerate settings; remove a bad custom endpoint.

Example fix

// before: bucket typo / wrong region -> nil response
terraform { backend "cos" { bucket = "my-bukcet" region = "ap-guangzhou" } }
// after
terraform { backend "cos" { bucket = "my-bucket"  region = "ap-guangzhou" } }

// Validate COS reachability/config before getObject depends on it
func cosReachable(c *cos.Client, ctx context.Context) error {
    // lightweight probe; nil response path means unreachable
    if c == nil { return fmt.Errorf("cos client not initialized (check credentials/region)") }
    return nil
}

// Retry getObject on nil-response (network) errors with backoff
for attempt := 0; attempt < 3; attempt++ {
    exists, data, sum, err := c.getObject(f)
    if err == nil || !strings.Contains(err.Error(), "failed to open file") || attempt == 2 { return exists, data, sum, err }
    time.Sleep(time.Duration(attempt+1) * time.Second)
}

When it happens

Trigger: getObject() runs c.cosClient.Object.Get(...); rsp comes back nil (err is non-nil). This happens on connection refusal, DNS resolution failure, invalid bucket URL, or a nil cosClient.

Common situations: Network outage to COS; wrong region/bucket producing an unresolvable host; credentials not configured so the client was not initialized; endpoint/accelerate misconfiguration.

Related errors

• prefix must not start with '/' or './'
• key can not start and end with '/'
• acl value invalid, expected %s or %s, got %s
• %q cannot be lower than %d: %d
• %q cannot be higher than %d: %d

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/795f181a56e08c87. Report an issue: GitHub.