hashicorp/terraform · error

workspace %s not found The configured "remote" backend retu

Error message

workspace %s not found

The configured "remote" backend returns '404 Not Found' errors for resources
that do not exist, as well as for resources that a user doesn't have access
to. If the resource does exist, please check the rights for the used token

What it means

Returned by fetchWorkspace() when Workspaces.Read fails with tfe.ErrResourceNotFound (HTTP 404). The message explicitly warns that the remote API returns 404 both for resources that do not exist AND for resources the token cannot access, so the real cause could be either a missing workspace or an authorization gap.

Source

Thrown at internal/backend/remote/backend.go:741

		// by this special case.
		DisableIntermediateSnapshots: client.runID != "",
	}, diags
}

func isLocalExecutionMode(execMode string) bool {
	return execMode == "local"
}

func (b *Remote) fetchWorkspace(ctx context.Context, organization string, name string) (*tfe.Workspace, error) {
	remoteWorkspaceName := b.getRemoteWorkspaceName(name)
	// Retrieve the workspace for this operation.
	w, err := b.client.Workspaces.Read(ctx, b.organization, remoteWorkspaceName)
	if err != nil {
		switch err {
		case context.Canceled:
			return nil, err
		case tfe.ErrResourceNotFound:
			return nil, fmt.Errorf(
				"workspace %s not found\n\n"+
					"The configured \"remote\" backend returns '404 Not Found' errors for resources\n"+
					"that do not exist, as well as for resources that a user doesn't have access\n"+
					"to. If the resource does exist, please check the rights for the used token",
				name,
			)
		default:
			err := fmt.Errorf(
				"the configured \"remote\" backend encountered an unexpected error:\n\n%s",
				err,
			)
			return nil, err
		}
	}

	return w, nil
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Verify the exact workspace name: check getRemoteWorkspaceName() output — if a prefix is set the actual name is prefix+localName.
2. Confirm the token's team has at least read access to that specific workspace (Workspace Settings > Team Access).
3. Make sure `organization` in the backend block is correct and the workspace lives under it.
4. If the workspace genuinely does not exist, create it in the UI or via `terraform workspace new`.

Example fix

// before - prefix produces wrong name, token lacks access
backend "remote" {
  organization = "acme"
  workspaces { prefix = "myapp-" }  // local "default" -> "myapp-default"
}

// after - fix the prefix OR grant the team read access to
//         the workspace "myapp-default" in the UI

// Resolve the real remote name (mirrors getRemoteWorkspaceName) and precheck.
func resolveName(local, prefix, exact string) string {
    if local == "default" { return exact }
    if prefix != "" && !strings.HasPrefix(local, prefix) { return prefix + local }
    return local
}

func isAccessDenied404(err error) bool {
    // 404 ambiguously means missing OR no-access; cannot distinguish client-side.
    return errors.Is(err, tfe.ErrResourceNotFound)
}

w, err := b.fetchWorkspace(ctx, org, name)
if err != nil {
    if errors.Is(err, context.Canceled) { return err }
    // surface the helpful 'not found or no access' message to the user
    return err
}

When it happens

Trigger: Calling Operation() (plan/apply/refresh) which calls fetchWorkspace(); the resolved remote workspace name (after prefix logic in getRemoteWorkspaceName) does not exist in the org, or the token's team lacks read access to it (the API responds 404 instead of 403 to avoid leaking existence).

Common situations: Workspace name typo in the backend block; wrong `prefix` so the derived name is wrong; the workspace exists but belongs to a different org; the token's team was not granted access to that workspace; using a VCS-connected workspace name that differs from the configured one.

Related errors

• Failed to retrieve workspace %s: %v
• retrieving container client: %v
• Error creating workspace %s: %v
• the configured "remote" backend encountered an unexpected er
• error finding remote workspace: %w

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