A required environment variable is missing. Set S3_BUCKET or

Error message

A required environment variable is missing. Set S3_BUCKET or TEST_WITH_LOCAL_FS and try again.

What it means

Thrown by the module.exports factory in the gatsby-transformer-screenshot Lambda when neither S3_BUCKET nor TEST_WITH_LOCAL_FS is set in the environment. The factory must choose between an S3-backed and a local-filesystem-backed screenshot backend; without either flag it cannot operate.

Source

Thrown at packages/gatsby-transformer-screenshot/lambda/screenshot.js:143

  return new Promise((resolve, reject) => {
    s3.getBucketLocation(params, (err, data) => {
      if (err) resolve(null)
      else resolve(data.LocationConstraint)
    })
  })
}

module.exports = opts => {
  if (process.env.S3_BUCKET) {
    return new S3Screenshot(opts)
  }

  if (process.env.TEST_WITH_LOCAL_FS) {
    return new FSScreenshot(opts)
  }

  throw new Error(
    `A required environment variable is missing. Set S3_BUCKET or TEST_WITH_LOCAL_FS and try again.`
  )
}

View on GitHub (pinned to 8b06340921)

Solutions

Set S3_BUCKET=<your-bucket-name> in the Lambda's environment for production screenshot storage.
For local development or testing, set TEST_WITH_LOCAL_FS=true to use the filesystem-backed FSScreenshot backend.
Add a startup check or health-check in your deployment script that asserts at least one variable is present before the Lambda receives traffic.
Document required env vars in the Lambda's README or serverless.yml environment block.

Example fix

// before — no env vars set
// Lambda crashes on cold start

// after (local dev / CI)
TEST_WITH_LOCAL_FS=true node lambda.js

// after (production)
# serverless.yml
functions:
  screenshot:
    environment:
      S3_BUCKET: ${env:S3_BUCKET}

Defensive patterns

Strategy: validation

Validate before calling

// Validate env vars at module load or Lambda init
function requireEnv(vars) {
  const missing = vars.filter(v => !process.env[v])
  if (missing.length) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`)
  }
}

// Check before requiring screenshot module
if (!process.env.S3_BUCKET && !process.env.TEST_WITH_LOCAL_FS) {
  console.error('Set S3_BUCKET or TEST_WITH_LOCAL_FS')
  // fail fast with a clear message rather than at request time
}

Prevention

Document required env vars in a .env.example committed to the repo.
Use a startup validation library (e.g. envalid, dotenv-safe) that fails fast on missing vars.
Set env vars in the Lambda configuration via serverless.yml or AWS Console.
Add a CI step that asserts required env vars are present in the deployment config.

When it happens

Trigger: The Lambda function is invoked (or the module is required in a test/CI context) without setting either environment variable. The factory immediately throws before constructing any backend object.

Common situations: Deploying the Lambda without configuring environment variables, running tests locally without TEST_WITH_LOCAL_FS=true, or a CI pipeline that drops env vars between stages. New developers who cloned the repo but didn't copy the .env.example.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/d9074055540b3e66. Report an issue: GitHub.