temporalio/temporal · error

requested bucket does not exist

Error message

requested bucket does not exist

What it means

errBucketNotExists is an unexported sentinel in common/archiver/s3store indicating the S3 bucket referenced by the archival URI does not exist. ValidateURI returns it after a HeadBucket-style BucketExists check; getHighestVersion translates AWS NoSuchBucket errors into it; and Upload/Download surface it when S3 rejects operations on a missing bucket.

Source

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

	"go.temporal.io/server/common/config"
	"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

View on GitHub (pinned to bde624efd1)

Solutions

1. Create the bucket (aws s3 mb s3://<bucket> --region <region>) or correct the bucket name in the namespace archival URI.
2. Verify the bucket exists in the configured region and that s3config.Region matches the bucket's region.
3. Check IAM permissions: the archiver needs HeadBucket/ListBucket as well as Get/PutObject.
4. If using a custom endpoint (S3-compatible storage), confirm the endpoint URL is correct and the bucket was created there.

Example fix

// before
uri, _ := archiver.NewURI("s3://temporal-archive-old/prod") // bucket was deleted
err := archiver.ValidateURI(uri) // errBucketNotExists

// after
// recreate or point at an existing bucket
uri, _ := archiver.NewURI("s3://temporal-archive/prod")
err := archiver.ValidateURI(uri) // nil

uri, err := archiver.NewURI(archiveURI)
if err != nil {
	return err
}
// historyArchiver.ValidateURI performs SoftValidateURI + BucketExists
if err := archiver.ValidateURI(uri); err != nil {
	return fmt.Errorf("archival target unusable: %w", err)
}

func isBucketNotExists(err error) bool {
	return errors.Is(err, errBucketNotExists) || strings.Contains(err.Error(), "does not exist")
}

resp, err := archiverClient.GetHistory(ctx, req)
if err != nil {
	var invalidArg *serviceerror.InvalidArgument
	if errors.As(err, &invalidArg) && strings.Contains(invalidArg.Message, "bucket does not exist") {
		// surface a config-fix hint instead of retrying
		return nil, fmt.Errorf("check archival bucket %q exists and region/IAM are correct", bucket)
	}
	return nil, err
}

When it happens

Trigger: historyArchiver.ValidateURI("s3://no-such-bucket/x") when BucketExists gets NoSuchBucket/404; getHighestVersion during Get when ListObjectsV2 returns *types.NoSuchBucket; Upload or Download calls hitting a deleted or never-created bucket during Archive/Get.

Common situations: Bucket deleted or renamed after the namespace was configured; typo in bucket name in the archival URI; wrong region — a bucket existing in another region can appear not to exist; IAM credentials lacking s3:ListBucket/HeadBucket so existence checks fail; using an S3-compatible endpoint where the bucket was not pre-created.

Related errors

• empty aws region
• no bucket specified
• SearchPrecision is required when searching for a StartTime o
• where expression is nil
• only comparison and "and" expression is supported

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