{"record":{"id":"c00901522000a68b","repo":"n8n-io/n8n","slug":"external-storage-bucket-name-not-configured-pleas","errorCode":null,"errorMessage":"External storage bucket name not configured. Please set `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME`.","messagePattern":"External storage bucket name not configured\\. Please set `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME`\\.","errorType":"exception","errorClass":"UnexpectedError","httpStatus":null,"severity":"critical","filePath":"packages/@n8n/blob-storage/src/object-store/object-store.service.ee.ts","lineNumber":48,"sourceCode":"\n/** How many per-key delete failures to name in the error before truncating, to keep the message bounded. */\nconst MAX_REPORTED_DELETE_ERRORS = 5;\n\n@Service()\nexport class ObjectStoreService {\n\tprivate s3Client: S3Client;\n\n\tprivate isReady = false;\n\n\tprivate bucket: string;\n\n\tconstructor(\n\t\tprivate readonly logger: Logger,\n\t\tprivate readonly s3Config: ObjectStoreConfig,\n\t) {\n\t\tconst { bucket } = s3Config;\n\t\tif (bucket.name === '') {\n\t\t\tthrow new UnexpectedError(\n\t\t\t\t'External storage bucket name not configured. Please set `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME`.',\n\t\t\t);\n\t\t}\n\n\t\tthis.bucket = bucket.name;\n\t\tthis.s3Client = new S3Client(this.getClientConfig());\n\t}\n\n\t/** This generates the config for the S3Client to make it work in all various auth configurations */\n\tgetClientConfig() {\n\t\tconst { host, bucket, protocol, credentials, maxAttempts } = this.s3Config;\n\t\tconst clientConfig: S3ClientConfig = {};\n\t\tconst endpoint = host ? `${protocol}://${host}` : undefined;\n\t\tif (endpoint) {\n\t\t\tclientConfig.endpoint = endpoint;\n\t\t\tclientConfig.forcePathStyle = this.s3Config.forcePathStyle;\n\t\t}\n\t\tif (bucket.region.length) {","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/blob-storage/src/object-store/object-store.service.ee.ts#L30-L66","documentation":"UnexpectedError thrown in the ObjectStoreService constructor when s3Config.bucket.name === ''. The bucket name comes from N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME. Notably this uses UnexpectedError (a code bug class) rather than UserError, which is inconsistent with the Azure equivalent [251]; functionally it still fails fast at DI time when S3 mode is enabled without a bucket.","triggerScenarios":"ObjectStoreService is instantiated via DI while N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME is empty AND external storage mode is s3. The constructor check at line 47 throws before any S3 client call.","commonSituations":"Switching N8N_EXTERNAL_STORAGE_MODE=s3 without setting the bucket env var; a typo in the env var; Helm/Kubernetes values file missing the bucket key; an env loader that strips empty values.","solutions":["Set N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME to a bucket n8n can read/write.","Verify the variable is present in the running process (printenv).","If S3 is not intended, switch N8N_EXTERNAL_STORAGE_MODE back to filesystem.","Restart n8n after setting the variable."],"exampleFix":"# before\nN8N_EXTERNAL_STORAGE_MODE=s3\n# bucket name missing\n\n# after\nN8N_EXTERNAL_STORAGE_MODE=s3\nN8N_EXTERNAL_STORAGE_S3_BUCKET_NAME=n8n-blobs","handlingStrategy":"validation","validationCode":"function assertS3Config(env: NodeJS.ProcessEnv) {\n  if (env.N8N_EXTERNAL_STORAGE_MODE === 's3' && !env.N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME) {\n    throw new Error('N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME must be set when mode=s3');\n  }\n}","typeGuard":"const hasS3Bucket = (env: NodeJS.ProcessEnv): boolean =>\n  !!env.N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME && env.N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME.length > 0;","tryCatchPattern":"try {\n  await objectStoreService.init();\n} catch (e) {\n  if (e instanceof UnexpectedError && /bucket name not configured/.test(e.message)) {\n    // halt startup with a clear config-missing message\n  }\n  throw e;\n}","preventionTips":["Add all N8N_EXTERNAL_STORAGE_S3_* keys to the deployment template.","Validate env vars in a pre-startup checklist before DI constructs services.","Note this throws UnexpectedError (not UserError) — classify accordingly in handlers."],"tags":["s3","blob-storage","config","env-vars","startup"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}