From 8161bc3ab9af6dbb4a976bee76658719e85c804b Mon Sep 17 00:00:00 2001
From: CJ Horton <cjhorton@hashicorp.com>
Date: Tue, 11 May 2021 23:28:22 -0700
Subject: [PATCH] backend/remote: clearer error when org read fails

When we fail to read the organization entitlements, it's not
always because the organization doesn't exist; in practice, it's
usually due to a misspelled organization name, forgetting to
specify the correct hostname, or an invalid API token. Surfacing
more information within the error message will help new users
debug these issues more effectively.
---
 backend/remote/backend.go      | 13 +++++++------
 backend/remote/backend_test.go |  2 +-
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/backend/remote/backend.go b/backend/remote/backend.go
index 43eb77fbc..880a384ba 100644
--- a/backend/remote/backend.go
+++ b/backend/remote/backend.go
@@ -321,15 +321,16 @@ func (b *Remote) Configure(obj cty.Value) tfdiags.Diagnostics {
 	entitlements, err := b.client.Organizations.Entitlements(context.Background(), b.organization)
 	if err != nil {
 		if err == tfe.ErrResourceNotFound {
-			err = fmt.Errorf("organization %s does not exist", b.organization)
+			err = fmt.Errorf("organization %q at host %s not found.\n\n"+
+				"Please ensure that the organization and hostname are correct "+
+				"and that your API token for %s is valid.",
+				b.organization, b.hostname, b.hostname)
 		}
 		diags = diags.Append(tfdiags.AttributeValue(
 			tfdiags.Error,
-			"Failed to read organization entitlements",
-			fmt.Sprintf(
-				`The "remote" backend encountered an unexpected error while reading the `+
-					`organization settings: %s.`, err,
-			),
+			fmt.Sprintf("Failed to read organization %q at host %s", b.organization, b.hostname),
+			fmt.Sprintf("The \"remote\" backend encountered an unexpected error while reading the "+
+				"organization settings: %s", err),
 			cty.Path{cty.GetAttrStep{Name: "organization"}},
 		))
 		return diags
diff --git a/backend/remote/backend_test.go b/backend/remote/backend_test.go
index 051d56410..fd6660685 100644
--- a/backend/remote/backend_test.go
+++ b/backend/remote/backend_test.go
@@ -55,7 +55,7 @@ func TestRemote_config(t *testing.T) {
 					"prefix": cty.NullVal(cty.String),
 				}),
 			}),
-			confErr: "organization nonexisting does not exist",
+			confErr: "organization \"nonexisting\" at host app.terraform.io not found",
 		},
 		"with_an_unknown_host": {
 			config: cty.ObjectVal(map[string]cty.Value{