{"record":{"id":"d9074055540b3e66","repo":"gatsbyjs/gatsby","slug":"a-required-environment-variable-is-missing-set-s3","errorCode":null,"errorMessage":"A required environment variable is missing. Set S3_BUCKET or TEST_WITH_LOCAL_FS and try again.","messagePattern":"A required environment variable is missing\\. Set S3_BUCKET or TEST_WITH_LOCAL_FS and try again\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby-transformer-screenshot/lambda/screenshot.js","lineNumber":143,"sourceCode":"\n  return new Promise((resolve, reject) => {\n    s3.getBucketLocation(params, (err, data) => {\n      if (err) resolve(null)\n      else resolve(data.LocationConstraint)\n    })\n  })\n}\n\nmodule.exports = opts => {\n  if (process.env.S3_BUCKET) {\n    return new S3Screenshot(opts)\n  }\n\n  if (process.env.TEST_WITH_LOCAL_FS) {\n    return new FSScreenshot(opts)\n  }\n\n  throw new Error(\n    `A required environment variable is missing. Set S3_BUCKET or TEST_WITH_LOCAL_FS and try again.`\n  )\n}\n","sourceCodeStart":125,"sourceCodeEnd":147,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-transformer-screenshot/lambda/screenshot.js#L125-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before — no env vars set\n// Lambda crashes on cold start\n\n// after (local dev / CI)\nTEST_WITH_LOCAL_FS=true node lambda.js\n\n// after (production)\n# serverless.yml\nfunctions:\n  screenshot:\n    environment:\n      S3_BUCKET: ${env:S3_BUCKET}","handlingStrategy":"validation","validationCode":"// Validate env vars at module load or Lambda init\nfunction requireEnv(vars) {\n  const missing = vars.filter(v => !process.env[v])\n  if (missing.length) {\n    throw new Error(`Missing required env vars: ${missing.join(', ')}`)\n  }\n}\n\n// Check before requiring screenshot module\nif (!process.env.S3_BUCKET && !process.env.TEST_WITH_LOCAL_FS) {\n  console.error('Set S3_BUCKET or TEST_WITH_LOCAL_FS')\n  // fail fast with a clear message rather than at request time\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["environment-variables","lambda","configuration","s3","gatsby-transformer-screenshot"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}