What causes "empty aws region" in temporalio/temporal?

Set region explicitly in the s3store archiver config (e.g. `s3store: { region: us-east-1 }`) and restart the history service.

temporalio/temporal · error

empty aws region

Error message

empty aws region

What it means

errEmptyAwsRegion is an unexported sentinel in common/archiver/s3store returned by newHistoryArchiver when config.S3Archiver.Region is an empty string. Before loading AWS credentials/config it requires an explicit region, because S3 is regional and requests without one fail with confusing AWS-side errors.

Source

Thrown at common/archiver/s3store/history_archiver.go:42

	"go.temporal.io/server/common/log"
	"go.temporal.io/server/common/log/tag"
	"go.temporal.io/server/common/metrics"
	"go.temporal.io/server/common/persistence"
)

const (
	// URIScheme is the scheme for the s3 implementation
	URIScheme               = "s3"
	errEncodeHistory        = "failed to encode history batches"
	errWriteKey             = "failed to write history to s3"
	defaultBlobstoreTimeout = time.Minute
	targetHistoryBlobSize   = 2 * 1024 * 1024 // 2MB
)

var (
	errNoBucketSpecified = errors.New("no bucket specified")
	errBucketNotExists   = errors.New("requested bucket does not exist")
	errEmptyAwsRegion    = errors.New("empty aws region")

	// the retryer is used to check if the error is retryable
	awsRetryer aws.Retryer = retry.NewStandard()
)

type (
	historyArchiver struct {
		executionManager persistence.ExecutionManager
		logger           log.Logger
		metricsHandler   metrics.Handler
		s3cli            S3API
		// only set in test code
		historyIterator archiver.HistoryIterator
	}

	getHistoryToken struct {
		CloseFailoverVersion int64
		BatchIdx             int

View on GitHub (pinned to bde624efd1)

Solutions

Set region explicitly in the s3store archiver config (e.g. `s3store: { region: us-east-1 }`) and restart the history service.
Check templated config rendering so the region variable is actually substituted.
Ensure GetHistoryArchiver is called with the right config pointer — a nil or empty S3Archiver in tests should be given a Region before use.

Example fix

// config before
s3store:
  logLevel: "error" // no region -> errEmptyAwsRegion

// config after
s3store:
  region: "us-east-1"
  logLevel: "error"

Defensive patterns

Strategy: validation

Validate before calling

if s3ArchiverConfig.Region == "" {
	return errors.New("s3store archiver config requires a non-empty region")
}

Prevention

Always set region explicitly in the s3store archiver config block; do not rely on AWS default region chains.
Validate rendered config files (after templating/env substitution) for empty required fields at startup.
Include the s3store region in config schema validation and CI checks.

When it happens

Trigger: Calling s3store.NewHistoryArchiver (via provider.GetHistoryArchiver("s3")) with an S3Archiver config whose Region field is empty — e.g. the s3store block present in config but the region key omitted or templated to an empty value.

Common situations: Region key missing from the config YAML; envsubst/config templating leaving {{ .Region }} empty; copying an S3 config example that relies on ambient AWS default region resolution which this code intentionally does not allow.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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