serverless/serverless · error · ServerlessError

REFERENCE_MODE_BUCKET_NOT_VERSIONED

REFERENCE_MODE_BUCKET_NOT_VERSIONED

Error message

Deployment bucket "${this.bucketName}" must have versioning enabled to use "codeStorageMode: reference". Enable versioning on the bucket, or remove the codeStorageMode setting.

What it means

Error "Deployment bucket "${this.bucketName}" must have versioning enabled to use "codeStorageMode: reference". Enable versioning on the bucket, or remove the codeStorageMode setting." thrown in serverless/serverless.

Source

Thrown at packages/serverless/lib/plugins/aws/deploy/lib/ensure-reference-code-storage.js:77

      this.buildReferencePolicyStatement(await this.provider.getAccountId()),
    )
    await this.provider.request('S3', 'putBucketPolicy', {
      Bucket: this.bucketName,
      Policy: JSON.stringify(policy),
    })
    log.info(
      `Granted the Lambda service read access to deployment bucket "${this.bucketName}" (self-managed code storage)`,
    )
  },

  async validateCustomBucketForReferenceMode() {
    const versioning = await this.provider.request(
      'S3',
      'getBucketVersioning',
      { Bucket: this.bucketName },
    )
    if (versioning.Status !== 'Enabled') {
      throw new ServerlessError(
        `Deployment bucket "${this.bucketName}" must have versioning enabled to use "codeStorageMode: reference". ` +
          'Enable versioning on the bucket, or remove the codeStorageMode setting.',
        'REFERENCE_MODE_BUCKET_NOT_VERSIONED',
      )
    }

    // Best-effort policy check — the framework never mutates user-owned buckets
    let result
    try {
      result = await this.provider.request('S3', 'getBucketPolicy', {
        Bucket: this.bucketName,
      })
    } catch (error) {
      const isNoSuchBucketPolicy =
        error.providerError?.code === 'NoSuchBucketPolicy' ||
        error.code === 'AWS_S3_GET_BUCKET_POLICY_NO_SUCH_BUCKET_POLICY'
      if (!isNoSuchBucketPolicy) {
        // Cannot read the policy for some other reason (e.g. AccessDenied) —

View on GitHub (pinned to b9d7ea51c8)

Solutions

1. Enable versioning on the deployment bucket (aws s3api put-bucket-versioning) or remove 'codeStorageMode: reference' from the configuration.

When it happens

Trigger: Thrown at packages/serverless/lib/plugins/aws/deploy/lib/ensure-reference-code-storage.js:77 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/143154513f857a1b. Report an issue: GitHub.