hashicorp/terraform · error

Attempted to find configured project

Error message

Attempted to find configured project %s but was unable to.

What it means

During StateMgr initialization, when a project is configured in the workspace mapping, the backend queries the TFE/HCP API for projects matching the name. If the Projects.List call fails with any error other than tfe.ErrResourceNotFound, this error is returned and state manager initialization fails. Note: if the project is simply not found (nil result), it is handled non-fatally (logged at line 769), but an actual API request failure is fatal.

Solutions

1. Ensure the API token has read access to projects in the organization.
2. Verify the TFE/HCP Terraform instance supports the Projects API (TFE 202208-x or later).
3. Retry the operation if the error was transient.
4. If projects are not needed, remove the 'project' attribute from the workspaces block.

Example fix

# before — project configured but API access fails
cloud {
  organization = "my-org"
  workspaces {
    tags    = ["env:prod"]
    project = "platform"
  }
}

# after — remove project if unsupported, or fix permissions
cloud {
  organization = "my-org"
  workspaces {
    tags = ["env:prod"]
  }
}
# Alternatively, ensure token has project read perms and TFE supports Projects API

// Before StateMgr init, verify project API is accessible
if b.WorkspaceMapping.Project != "" {
    resp, err := b.client.Projects.List(ctx, b.Organization, listOpts)
    if err != nil && err != tfe.ErrResourceNotFound {
        return fmt.Errorf("projects API not accessible: %w", err)
    }
    _ = resp
}

// Retry project listing during StateMgr init
for i := 0; i < 3; i++ {
    projects, err := b.client.Projects.List(ctx, b.Organization, listOpts)
    if err == nil || err == tfe.ErrResourceNotFound {
        break
    }
    if i == 2 {
        return nil, diags.Append(fmt.Errorf("Attempted to find configured project %s but was unable to.", b.WorkspaceMapping.Project))
    }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

When it happens

Trigger: Calling b.client.Projects.List at backend.go:753 returns a non-nil, non-404 error. This occurs when the API request itself fails — authentication errors, permission denied, rate limiting, server errors, or network issues. The error message specifically says 'was unable to', indicating the request could not be completed, not that the project was absent.

Common situations: The API token lacks permissions to list projects. The TFE instance version predates the Projects API. Transient network errors during 'terraform init' or 'terraform plan'. Rate limiting from concurrent operations. The organization name is incorrect, causing an API-level error.

Related errors

• failed to retrieve project
• Failed to retrieve workspace
• failed to retrieve workspace
• organization at host not found. Please ensure that the…
• a network issue prevented cloud configuration;

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/672829ec8d5a53f8. Report an issue: GitHub.

Appendix: source

Thrown at internal/cloud/backend.go:756

	workspace, err := b.client.Workspaces.Read(context.Background(), b.Organization, name)
	if err != nil && err != tfe.ErrResourceNotFound {
		return nil, diags.Append(fmt.Errorf("Failed to retrieve workspace %s: %v", name, err))
	}
	if workspace != nil {
		remoteTFVersion = workspace.TerraformVersion
	}

	var configuredProject *tfe.Project

	// Attempt to find project if configured
	if b.WorkspaceMapping.Project != "" {
		listOpts := &tfe.ProjectListOptions{
			Name: b.WorkspaceMapping.Project,
		}
		projects, err := b.client.Projects.List(context.Background(), b.Organization, listOpts)
		if err != nil && err != tfe.ErrResourceNotFound {
			// This is a failure to make an API request, fail to initialize
			return nil, diags.Append(fmt.Errorf("Attempted to find configured project %s but was unable to.", b.WorkspaceMapping.Project))
		}
		for _, p := range projects.Items {
			if p.Name == b.WorkspaceMapping.Project {
				configuredProject = p
				break
			}
		}

		if configuredProject == nil {
			// We were able to read project, but were unable to find the configured project
			// This is not fatal as we may attempt to create the project if we need to create
			// the workspace
			log.Printf("[TRACE] cloud: Attempted to find configured project %s but was unable to.", b.WorkspaceMapping.Project)
		}
	}

	if err == tfe.ErrResourceNotFound {
		// Create workspace if it was not found

View on GitHub (pinned to d32a084675)