hashicorp/terraform · error

remote backend doesn't support

Error message

remote backend doesn't support %s

What it means

A defensive guard in the plan-mode switch: NormalMode, RefreshOnlyMode and DestroyMode are explicitly mapped to RunCreateOptions; any other plans.Mode value falls into default and aborts. The comment states this should be updated for every new mode added, so hitting it means a code/version skew rather than a user mistake.

Solutions

1. Run plan/apply with a supported mode (default, -refresh-only, or -destroy) against the remote backend.
2. If you genuinely need the new mode, file an issue / update this switch to map it to the corresponding RunCreateOptions field.
3. Pin to a Terraform version whose plan-mode set matches the remote backend implementation.
4. For a local fork, add the case here and verify the TFC RunCreateOptions field exists for it.

Example fix

// before
case plans.NormalMode:
case plans.RefreshOnlyMode:
case plans.DestroyMode:
// after (after adding support for a hypothetical mode)
case plans.SomeNewMode:
    runOptions.SomeNewFlag = tfe.Bool(true)

// Guard against unsupported plan mode before dispatching to remote backend
switch mode {
case plans.NormalMode, plans.RefreshOnlyMode, plans.DestroyMode:
    // ok
default:
    return fmt.Errorf("plan mode %s not supported by remote backend", mode)
}

func isRemoteSupportedMode(m plans.Mode) bool {
    switch m {
    case plans.NormalMode, plans.RefreshOnlyMode, plans.DestroyMode:
        return true
    }
    return false
}

When it happens

Trigger: A new plans.Mode constant was added to core but the remote backend switch was not updated; an experimentally-enabled plan mode reached the remote backend; a custom/forked build introduced a new mode without backend support.

Common situations: Running a fork or unreleased build that adds a plan mode before the TFC run-creation layer supports it; mixing incompatible Terraform core + TFE server versions where the server rejects the implicit mapping.

Related errors

• Task stage ' ' has invalid status
• approved using the UI or API
• discarded using the UI or API
• error deleting workspace
• Error downloading state

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

Appendix: source

Thrown at internal/backend/remote/backend_plan.go:315

		ConfigurationVersion: cv,
		Refresh:              tfe.Bool(op.PlanRefresh),
		Workspace:            w,
	}

	switch op.PlanMode {
	case plans.NormalMode:
		// okay, but we don't need to do anything special for this
	case plans.RefreshOnlyMode:
		runOptions.RefreshOnly = tfe.Bool(true)
	case plans.DestroyMode:
		runOptions.IsDestroy = tfe.Bool(true)
	default:
		// Shouldn't get here because we should update this for each new
		// plan mode we add, mapping it to the corresponding RunCreateOptions
		// field.
		return nil, generalError(
			"Invalid plan mode",
			fmt.Errorf("remote backend doesn't support %s", op.PlanMode),
		)
	}

	if len(op.Targets) != 0 {
		runOptions.TargetAddrs = make([]string, 0, len(op.Targets))
		for _, addr := range op.Targets {
			runOptions.TargetAddrs = append(runOptions.TargetAddrs, addr.String())
		}
	}

	if len(op.ForceReplace) != 0 {
		runOptions.ReplaceAddrs = make([]string, 0, len(op.ForceReplace))
		for _, addr := range op.ForceReplace {
			runOptions.ReplaceAddrs = append(runOptions.ReplaceAddrs, addr.String())
		}
	}

	r, err := b.client.Runs.Create(stopCtx, runOptions)

View on GitHub (pinned to d32a084675)