{"record":{"id":"904f34d0bde7c7c0","repo":"temporalio/temporal","slug":"unknown-archiver-scheme","errorCode":null,"errorMessage":"unknown archiver scheme","messagePattern":"unknown archiver scheme","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/archiver/provider/provider.go","lineNumber":21,"sourceCode":"package provider\n\nimport (\n\t\"errors\"\n\t\"sync\"\n\n\t\"go.temporal.io/server/common/archiver\"\n\t\"go.temporal.io/server/common/archiver/filestore\"\n\t\"go.temporal.io/server/common/archiver/gcloud\"\n\t\"go.temporal.io/server/common/archiver/s3store\"\n\t\"go.temporal.io/server/common/config\"\n\t\"go.temporal.io/server/common/log\"\n\t\"go.temporal.io/server/common/metrics\"\n\t\"go.temporal.io/server/common/persistence\"\n)\n\nvar (\n\t// ErrUnknownScheme is the error for unknown archiver scheme\n\tErrUnknownScheme = errors.New(\"unknown archiver scheme\")\n\t// ErrArchiverConfigNotFound is the error for unable to find the config for an archiver given scheme\n\tErrArchiverConfigNotFound = errors.New(\"unable to find archiver config for the given scheme\")\n)\n\ntype (\n\t// ArchiverProvider returns history or visibility archiver based on the scheme.\n\t// The archiver for each scheme will be created only once and cached.\n\tArchiverProvider interface {\n\t\tGetHistoryArchiver(scheme string) (archiver.HistoryArchiver, error)\n\t\tGetVisibilityArchiver(scheme string) (archiver.VisibilityArchiver, error)\n\t}\n\n\t// NewCustomHistoryArchiverParams provides dependencies for constructing a history archiver.\n\tNewCustomHistoryArchiverParams struct {\n\t\tScheme           string\n\t\tExecutionManager persistence.ExecutionManager\n\t\tLogger           log.Logger\n\t\tMetricsHandler   metrics.Handler","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/archiver/provider/provider.go#L3-L39","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the scheme in the namespace archival URI / config to one of the supported values: \"filestore\", \"gs\" (gcloud), or \"s3\".","Register a CustomHistoryArchiverFactory/CustomVisibilityArchiverFactory that handles the scheme (returning a non-nil archiver) if you use a custom blobstore.","Compare the scheme against the exported URIScheme constants (filestore.URIScheme, gcloud.URIScheme, s3store.URIScheme) rather than hardcoding strings.","Use errors.Is(err, provider.ErrUnknownScheme) to distinguish this from config-missing or construction failures."],"exampleFix":"// before\narch, err := archiverProvider.GetHistoryArchiver(\"S3\") // ErrUnknownScheme\n\n// after\narch, err := archiverProvider.GetHistoryArchiver(s3store.URIScheme) // \"s3\"","handlingStrategy":"type-guard","validationCode":"supported := map[string]bool{\"filestore\": true, \"gs\": true, \"s3\": true}\nif !supported[scheme] {\n\treturn nil, fmt.Errorf(\"scheme %q not supported; register a custom archiver factory\", scheme)\n}","typeGuard":"func isKnownArchiverScheme(err error) bool { return errors.Is(err, provider.ErrUnknownScheme) }","tryCatchPattern":"histArchiver, err := archiverProvider.GetHistoryArchiver(scheme)\nif err != nil {\n\tif errors.Is(err, provider.ErrUnknownScheme) {\n\t\t// bad scheme in config/URI: fail fast with a clear message\n\t\treturn nil, fmt.Errorf(\"unsupported archival scheme %q\", scheme)\n\t}\n\treturn nil, err\n}","preventionTips":["Reference exported URIScheme constants instead of hardcoded scheme strings.","Validate namespace archival URIs at startup so unknown schemes fail fast.","When using custom archiver factories, return provider.ErrUnknownScheme only to mean 'not mine', never for real construction errors."],"tags":["archival","provider","uri-scheme","configuration"],"backgroundTag":"unknown-archiver-scheme","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}