hashicorp/terraform · error · ErrPluginNotFound

plugin download was not found in the location specified in t

Error message

plugin download was not found in the location specified in the manifest

What it means

ErrPluginNotFound is returned by DownloadFile when the download URL from the manifest returns HTTP 404 (client.go:224-225). The manifest exists and listed a build for this arch, but the actual archive URL it points to is missing — the manifest and the published artifacts are out of sync.

Source

Thrown at internal/pluginshared/errors.go:25

	"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
}

// ErrCloudPluginNotVerified is the error returned when the archive authentication process fails
type ErrCloudPluginNotVerified struct {
	inner error
}

// Error returns a string representation of ErrQueryFailed
func (e ErrQueryFailed) Error() string {
	return fmt.Sprintf("failed to fetch plugin from HCP Terraform: %s", e.inner)
}

// Unwrap returns the inner error of ErrQueryFailed

View on GitHub (pinned to d32a084675)

Solutions

1. Retry after a short delay if this coincides with a known release window (manifest may be ahead of artifacts).
2. Force-refresh the manifest (bypass cache / ETag 304) to ensure you are not reading a stale entry.
3. Verify the download host/path in the manifest is correct and reachable; check the upstream release assets actually exist.
4. Report to the plugin publisher if the 404 persists — it indicates a broken release.

Example fix

// before
err := client.DownloadFile(url, &buf)
if err != nil {
    return err
}

// after
err := client.DownloadFile(url, &buf)
if errors.Is(err, pluginshared.ErrPluginNotFound) {
    return fmt.Errorf("plugin archive %q is missing although the manifest lists it; retry later or report to the publisher", url)
}
if err != nil {
    return err
}

n/a — server-side artifact availability; cannot be validated client-side beyond an HTTP HEAD.

func isPluginNotFound(err error) bool {
    return errors.Is(err, pluginshared.ErrPluginNotFound)
}

err := client.DownloadFile(url, &buf)
if errors.Is(err, pluginshared.ErrPluginNotFound) {
    // retry a few times if a release is being published; otherwise report
    return maybeRetryOnReleaseWindow(err)
}

When it happens

Trigger: DownloadFile's switch hits case http.StatusNotFound at client.go:224. Common when a release was partially published (manifest updated before artifacts uploaded, or artifacts later removed), the URL was malformed, or a mirror is incomplete.

Common situations: Reading a manifest during a release cut-over window; mirror/CDN has not yet propagated the archive; manifest references a build that was yanked; stale cached manifest pointing at retired artifacts.

Related errors

• request was canceled
• plugin is not supported by your computer architecture/operat
• approved using the UI or API
• discarded using the UI or API
• operation timed out

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