hashicorp/terraform · error · ErrPluginNotSupported

plugin is not supported by the remote version of Terraform E

Error message

plugin is not supported by the remote version of Terraform Enterprise

What it means

ErrPluginNotSupported is returned by GetManifest when the manifest endpoint responds with HTTP 404. It indicates that the upstream HCP Terraform / TFE deployment does not publish a plugin manifest at all — i.e. this plugin type is not supported by the remote version of Terraform Enterprise. It is distinct from ErrPluginNotFound (a missing download) and ErrQueryFailed (other HTTP errors).

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 d32a084675)

Solutions

1. Confirm the HCP Terraform / TFE deployment supports this plugin (check release/version against the feature's introduction).
2. Verify the service URL and plugin name configured on the BasePluginClient.
3. Upgrade the TFE/HCP Terraform deployment to a version that publishes the plugin manifest.
4. Distinguish this case in callers with errors.Is(err, pluginshared.ErrPluginNotSupported) and surface a clear 'not supported by remote' message to the user.

Example fix

// before
manifest, err := client.GetManifest(url)
if err != nil {
    return err
}

// after
manifest, err := client.GetManifest(url)
if errors.Is(err, pluginshared.ErrPluginNotSupported) {
    return fmt.Errorf("the configured HCP Terraform / TFE instance does not support plugin %q; upgrade the deployment", pluginName)
}
if err != nil {
    return err
}

// Probe manifest support: a HEAD/GET that 404s on the manifest path
// indicates the upstream does not support this plugin.
// (Best done by calling GetManifest and checking the error.)

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

m, err := client.GetManifest(url)
if errors.Is(err, pluginshared.ErrPluginNotSupported) {
    // surface a clear 'upgrade your HCP Terraform / TFE' message; do not retry
    return errNotSupportedByRemote
}
if err != nil {
    return err
}

When it happens

Trigger: BasePluginClient.GetManifest issues a GET to the manifest path and receives 404 (client.go:192-193). This happens when the HCP Terraform / TFE version predates plugin manifest support, the plugin name is unknown to the upstream, or the service URL points at an instance that does not host this plugin.

Common situations: Pointing the plugin client at an older self-hosted TFE install that lacks the manifest endpoint; mismatch between the plugin name used by the client and what the upstream publishes; using a feature that requires a newer HCP Terraform release than is deployed.

Related errors

• your version of Terraform Enterprise does not support key-va
• unsupported action trigger type: %T
• saved backend configuration is invalid: %w
• resource schema not found for type %q
• list resource schema not found for type %q

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