hashicorp/terraform · error

failed to create project %s: %v

Error message

failed to create project %s: %v

What it means

Returned in backend StateMgr at backend.go:799 when b.client.Projects.Create returns a non-ErrResourceNotFound error while creating a project that did not exist, in order to host a new workspace. This path runs during workspace auto-creation (plan/apply) when the configured project is absent and the backend attempts to create it. %s=project name, %v=API error.

Source

Thrown at internal/cloud/backend.go:799

		if b.WorkspaceMapping.Strategy() == WorkspaceTagsStrategy {
			workspaceCreateOptions.Tags = b.WorkspaceMapping.tfeTags()
		} else if b.WorkspaceMapping.Strategy() == WorkspaceKVTagsStrategy {
			workspaceCreateOptions.TagBindings = b.WorkspaceMapping.asTFETagBindings()
		}

		// Create project if not exists, otherwise use it
		if workspaceCreateOptions.Project == nil && b.WorkspaceMapping.Project != "" {
			// If we didn't find the project, try to create it
			if workspaceCreateOptions.Project == nil {
				createOpts := tfe.ProjectCreateOptions{
					Name: b.WorkspaceMapping.Project,
				}
				// didn't find project, create it instead
				log.Printf("[TRACE] cloud: Creating %s project %s/%s", b.appName, b.Organization, b.WorkspaceMapping.Project)
				project, err := b.client.Projects.Create(context.Background(), b.Organization, createOpts)
				if err != nil && err != tfe.ErrResourceNotFound {
					return nil, diags.Append(fmt.Errorf("failed to create project %s: %v", b.WorkspaceMapping.Project, err))
				}
				configuredProject = project
				workspaceCreateOptions.Project = configuredProject
			}
		}

		// Create a workspace
		log.Printf("[TRACE] cloud: Creating %s workspace %s/%s", b.appName, b.Organization, name)
		workspace, err = b.client.Workspaces.Create(context.Background(), b.Organization, workspaceCreateOptions)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("error creating workspace %s: %v", name, err))
		}

		remoteTFVersion = workspace.TerraformVersion

		// Attempt to set the new workspace to use this version of Terraform. This
		// can fail if there's no enabled tool_version whose name matches our
		// version string, but that's expected sometimes -- just warn and continue.

View on GitHub (pinned to c9def3e214)

Solutions

1. Pre-create the project in the HCP/TFE UI so auto-create is not required.
2. Grant the token admin/project-create permission, or run with a token that has it.
3. Resolve 409 conflicts by renaming or restoring the existing project.

Example fix

// before: token cannot create projects, backend tries to auto-create
cloud { workspaces { project = "platform" name = "new-ws" } }

// after: pre-create project in UI, or use an admin token
cloud { workspaces { project = "platform" name = "new-ws" } }
# ensure token has 'Manage Projects' (admin) scope

// Pre-create the project (idempotent) to avoid auto-create failures at plan time.
func ensureProject(c *tfe.Client, org, name string) error {
    if _, err := c.Projects.Create(ctx, org, tfe.ProjectCreateOptions{Name: name}); err != nil {
        if !isConflict(err) { return err }
    }
    return nil
}

if errors.Is(err, tfe.ErrResourceNotFound) { /* tolerate */ } else if isConflict(err) { /* already exists */ }

project, err := b.client.Projects.Create(ctx, org, createOpts)
if err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {
    if isConflict(err) {
        // fetch existing instead
        project, err = findProjectByName(b.client, org, name)
    }
    if err != nil {
        return nil, fmt.Errorf("failed to create project %s: %v", name, err)
    }
}

When it happens

Trigger: terraform plan/apply with a cloud backend referencing a project that does not yet exist and workspaces that must be auto-created; Projects.Create fails (typically 401/403/409 conflict or 5xx).

Common situations: Token lacks project-create (admin) permission; a project of the same name already exists in a deleted state causing conflict; org billing limits on project count; API outage during create.

Related errors

• failed to retrieve project %s: %v
• Attempted to find configured project %s but was unable to.
• error creating workspace %s: %v
• failed to retrieve workspace %s: %v
• Failed to retrieve workspace %s: %v

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