hashicorp/terraform · error · ErrPluginNotSupported

ErrPluginNotSupported

ErrPluginNotSupported

Error message

plugin is not supported by the remote version of Terraform Enterprise

What it means

ErrPluginNotSupported is a sentinel error from the pluginshared manifest client, returned when HCP Terraform / Terraform Enterprise responds to the plugin manifest fetch (manifest.json) with HTTP 404. It indicates the remote platform version does not serve the plugin/manifest endpoint Terraform is querying, i.e. the running platform is older than what this CLI feature requires.

Source

Thrown at internal/pluginshared/errors.go:14

// Copyright IBM Corp. 2014, 2026
// SPDX-License-Identifier: BUSL-1.1

package pluginshared

import (
	"errors"
	"fmt"
)

var (
	// ErrPluginNotSupported is the error returned when the upstream HCP Terraform does not
	// have a manifest.
	ErrPluginNotSupported = errors.New("plugin is not supported by the remote version of Terraform Enterprise")

	// ErrRequestCanceled is the error returned when the context was cancelled.
	ErrRequestCanceled = errors.New("request was canceled")

	// ErrArchNotSupported is the error returned when the plugin does not have a build for the
	// current OS/Architecture.
	ErrArchNotSupported = errors.New("plugin is not supported by your computer architecture/operating system")

	// ErrPluginNotFound is the error returned when the plugin manifest points to a location
	// that was does not exist.
	ErrPluginNotFound = errors.New("plugin download was not found in the location specified in the manifest")
)

// ErrQueryFailed is the error returned when the plugin http client request fails
type ErrQueryFailed struct {
	inner error
}

View on GitHub (pinned to c9def3e214)

Solutions

Upgrade the HCP Terraform / TFE instance to a version that supports the plugin feature the CLI expects (check the platform release notes and the CLI's bundled plugin requirements).
Verify the service URL / hostname configuration is correct and routes to the intended, up-to-date tenant.
Downgrade the Terraform CLI to a version compatible with the deployed platform version if an immediate platform upgrade is not possible.
Confirm with the platform admin that the plugin distribution/manifest capability is enabled for the organization.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before relying on the manifest, probe a lightweight capability check.
// There is no public capability API; best pre-check is version compatibility doc.

Type guard

func isPluginNotSupported(err error) bool {
    return errors.Is(err, pluginshared.ErrPluginNotSupported)
}

Try / catch

rel, err := client.FetchManifest(lastModified)
switch {
case err == nil:
    // proceed
case errors.Is(err, pluginshared.ErrPluginNotSupported):
    // platform too old: guide user to upgrade HCP/TFE or downgrade CLI
    return fmt.Errorf("plugin feature unsupported by this HCP Terraform/TFE version; upgrade the platform or use an older Terraform CLI")
default:
    return err
}

Prevention

Keep the Terraform CLI and HCP/TFE versions within the documented compatibility matrix.
In automation, detect ErrPluginNotSupported and fail with an actionable message rather than a generic error.
Confirm hostname/app-token route to the intended upgraded tenant.

When it happens

Trigger: Produced in BasePluginClient.FetchManifest (internal/pluginshared/client.go:193) on resp.StatusCode == http.StatusNotFound from the serviceURL/manifest.json GET. The endpoint absence means the remote TFE/HCP install predates the plugin distribution feature.

Common situations: Upgrading the Terraform CLI to a version that fetches an internal plugin (e.g. a bundled tool) from a TFE/HCP instance that has not yet been upgraded to a compatible release. Pointing at an on-prem TFE install that lags behind the CLI. A misconfigured hostname/app token that routes to a different, older tenant.

Related errors

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