temporalio/temporal · error

unknown archiver scheme

Error message

unknown archiver scheme

What it means

ErrUnknownScheme is the sentinel error exported by common/archiver/provider for an archiver scheme that has no built-in implementation. GetHistoryArchiver/GetVisibilityArchiver return it when the URI scheme is not one of filestore, gcloud, or s3, and custom archiver factories return it to signal fallback to the built-in implementation. It is not a transient failure — the scheme string itself is wrong or unsupported.

Source

Thrown at common/archiver/provider/provider.go:21

package provider

import (
	"errors"
	"sync"

	"go.temporal.io/server/common/archiver"
	"go.temporal.io/server/common/archiver/filestore"
	"go.temporal.io/server/common/archiver/gcloud"
	"go.temporal.io/server/common/archiver/s3store"
	"go.temporal.io/server/common/config"
	"go.temporal.io/server/common/log"
	"go.temporal.io/server/common/metrics"
	"go.temporal.io/server/common/persistence"
)

var (
	// ErrUnknownScheme is the error for unknown archiver scheme
	ErrUnknownScheme = errors.New("unknown archiver scheme")
	// ErrArchiverConfigNotFound is the error for unable to find the config for an archiver given scheme
	ErrArchiverConfigNotFound = errors.New("unable to find archiver config for the given scheme")
)

type (
	// ArchiverProvider returns history or visibility archiver based on the scheme.
	// The archiver for each scheme will be created only once and cached.
	ArchiverProvider interface {
		GetHistoryArchiver(scheme string) (archiver.HistoryArchiver, error)
		GetVisibilityArchiver(scheme string) (archiver.VisibilityArchiver, error)
	}

	// NewCustomHistoryArchiverParams provides dependencies for constructing a history archiver.
	NewCustomHistoryArchiverParams struct {
		Scheme           string
		ExecutionManager persistence.ExecutionManager
		Logger           log.Logger
		MetricsHandler   metrics.Handler

View on GitHub (pinned to bde624efd1)

Solutions

1. Fix the scheme in the namespace archival URI / config to one of the supported values: "filestore", "gs" (gcloud), or "s3".
2. Register a CustomHistoryArchiverFactory/CustomVisibilityArchiverFactory that handles the scheme (returning a non-nil archiver) if you use a custom blobstore.
3. Compare the scheme against the exported URIScheme constants (filestore.URIScheme, gcloud.URIScheme, s3store.URIScheme) rather than hardcoding strings.
4. Use errors.Is(err, provider.ErrUnknownScheme) to distinguish this from config-missing or construction failures.

Example fix

// before
arch, err := archiverProvider.GetHistoryArchiver("S3") // ErrUnknownScheme

// after
arch, err := archiverProvider.GetHistoryArchiver(s3store.URIScheme) // "s3"

supported := map[string]bool{"filestore": true, "gs": true, "s3": true}
if !supported[scheme] {
	return nil, fmt.Errorf("scheme %q not supported; register a custom archiver factory", scheme)
}

func isKnownArchiverScheme(err error) bool { return errors.Is(err, provider.ErrUnknownScheme) }

histArchiver, err := archiverProvider.GetHistoryArchiver(scheme)
if err != nil {
	if errors.Is(err, provider.ErrUnknownScheme) {
		// bad scheme in config/URI: fail fast with a clear message
		return nil, fmt.Errorf("unsupported archival scheme %q", scheme)
	}
	return nil, err
}

When it happens

Trigger: Calling provider.GetHistoryArchiver("azblob") or any scheme outside "filestore"/"gs"/"s3" (the URIScheme constants) when no custom factory handles it. Also surfaces when a customHistoryArchiverFactory returns ErrUnknownScheme and the built-in switch also has no match. Note: custom factories returning this sentinel intentionally trigger fallback, so it becomes user-visible only when nothing else handles the scheme.

Common situations: Typo in archival config (e.g. "S3", "s3://" instead of "s3"); using a cloud provider without built-in support (Azure Blob); namespace archival URI scheme not matching the configured archiver; custom plugin removed but URIs still reference its scheme.

Related errors

• unable to find archiver config for the given scheme
• no bucket specified
• empty aws region
• SearchPrecision is required when searching for a StartTime o
• where expression is nil

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/904f34d0bde7c7c0. Report an issue: GitHub.