hashicorp/terraform · error

{joined API error payload}

Error message

{joined API error payload}

What it means

Generic error assembled by checkResponseCode() in the cloud backend for any non-2xx HTTP response that is not 401/404: decodeErrorPayload() reads the JSON:API errors array and this site joins each error's Title (+Detail) with newlines into one error string. The literal message is whatever the HCP/TFE API returned.

Source

Thrown at internal/cloud/backend_common.go:749

		return nil
	}

	var errs []string
	var err error

	switch r.StatusCode {
	case 401:
		return tfe.ErrUnauthorized
	case 404:
		return tfe.ErrResourceNotFound
	}

	errs, err = decodeErrorPayload(r)
	if err != nil {
		return err
	}

	return errors.New(strings.Join(errs, "\n"))
}

func decodeErrorPayload(r *http.Response) ([]string, error) {
	// Decode the error payload.
	var errs []string
	errPayload := &jsonapi.ErrorsPayload{}
	err := json.NewDecoder(r.Body).Decode(errPayload)
	if err != nil || len(errPayload.Errors) == 0 {
		return errs, errors.New(r.Status)
	}

	// Parse and format the errors.
	for _, e := range errPayload.Errors {
		if e.Detail == "" {
			errs = append(errs, e.Title)
		} else {
			errs = append(errs, fmt.Sprintf("%s\n\n%s", e.Title, e.Detail))
		}

View on GitHub (pinned to c9def3e214)

Solutions

1. Read the joined Title/Detail lines — they carry the backend's specific reason.
2. Address the underlying API error (fix the referenced resource/config), then retry.
3. If the error is a transient 5xx, retry with backoff; consult HCP/TFE status.
4. For 4xx, verify workspace/org/permissions and the request payload.

resp, err := b.client.Workspaces.Read(ctx, org, name)
if err != nil {
    // err is a joined string of JSON:API Title/Detail lines;
    // classify by known substrings or re-parse for structured handling.
    if strings.Contains(err.Error(), "not found") {
        // handle missing workspace
    }
    return err
}

When it happens

Trigger: Any HCP/TFE API call (readRedactedPlan, run/state APIs, etc.) returning 4xx/5xx with a parseable JSON:API error body — e.g. 422 validation errors, 500 server errors, 409 conflicts.

Common situations: Invalid workspace name; run conflicts; plan output no longer available; quota exceeded; backend-side validation failure surfaced as multiple JSON:API errors.

Related errors

• {r.Status}
• your version of Terraform Enterprise does not support key-va
• operation timed out
• error updating workspace %q tags: %w
• %s returned an unexpected error: %s

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