How to fix Reg-suit authentication failed with S3

If Reg-suit reports an S3 authentication failure, the message alone does not identify one confirmed cause. Check the bucket configured in Reg-suit, the AWS identity available to the exact process running Reg-suit, the S3 operation that failed, and the complete AWS SDK error. Then compare that operation with the identity’s effective permissions and applicable bucket access rules.

Reg-suit’s S3 publisher retrieves earlier snapshot images and publishes current snapshots and comparison reports. Its documented permissions are a useful checklist, not proof that a particular permission caused your failure. See the S3 publisher documentation and Reg-suit project documentation.

1. Read the complete failure before changing access

Record the full error, including the AWS error code and message, the operation named in the logs, and the job context. The phrase “authentication failed” does not, by itself, tell you whether AWS rejected credentials, accepted an identity that lacks permission for an operation, or encountered a different configuration problem. The cited Reg-suit documentation does not map that exact phrase to a single cause.

Do not paste access keys, session tokens, cookies, or authorization headers into logs or issue reports. Preserve the error details while redacting secret values.

2. Confirm the S3 publisher configuration and bucket

Inspect the plugins section of the regconfig.json used by the failing job. Confirm that the S3 publisher is configured and that its bucketName resolves to the intended bucket. Reg-suit supports environment-value interpolation in plugin configuration, so check the values available to the job process—not only values present on a developer’s laptop.

A minimal shape to compare with your project’s configuration is:

{
  "plugins": [
    {
      "name": "reg-publish-s3-plugin",
      "options": {
        "bucketName": "your-snapshot-bucket"
      }
    }
  ]
}

This is a configuration shape, not a complete project setup: retain your existing Reg-suit settings and use the actual package name and options required by your installed version. If your config interpolates an environment variable for the bucket, verify that it is set in the CI step that invokes Reg-suit and resolves to the expected value.

3. Verify the credentials available to Reg-suit

The Reg-suit demo shows two credential paths: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or a [default] profile in ~/.aws/credentials. These are examples, not a requirement to use long-lived keys in every environment. Whichever path your job uses, establish the identity seen by the process that runs Reg-suit through your CI platform’s safe identity-inspection mechanisms.

For a local environment using the documented default profile pattern, the credentials file has this form:

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

For an environment that supplies the documented variables, ensure both are present in the Reg-suit process environment. Never print their values as a diagnostic. A local shell’s credentials do not establish which identity a CI job uses; verify the job’s role or credentials in that environment.

4. Match permissions to the operation that failed

The S3 plugin README lists these IAM actions as requirements:

s3:DeleteObject
s3:GetObject
s3:GetObjectAcl
s3:PutObject
s3:PutObjectAcl
s3:ListBucket

Compare the failed operation in the complete error or logs with the effective identity’s permissions and the bucket’s access controls. Object actions and bucket listing apply at different resource scopes in AWS policies, so check that the rules cover the intended bucket and objects. The list is the plugin’s documented reference; it does not establish that any one action is missing from your policy.

Change only the policy or bucket rule supported by the observed failure. Do not grant broad access as a diagnostic shortcut.

5. Check S3 client options

The plugin exposes optional sdkOptions for its S3 client. If your project sets them, compare the effective settings supplied to the job with the intended environment and bucket. The cited Reg-suit material does not say that a region or SDK option mismatch specifically produces the title’s authentication text. Treat client settings as a configuration check, and use the full error to decide whether they are relevant.

6. Re-run the failing workflow and verify the result

Make the smallest change indicated by the error and configuration inspection.
Re-run the same CI job or local command with the same configuration path.
Confirm that Reg-suit can retrieve its earlier snapshots and publish the current snapshots and comparison reports.
If it still fails, capture the new complete error and check whether the failed operation or identity changed.

If the job succeeds locally but fails in CI, compare the effective configuration, bucket value, credentials or role context, and applicable access rules between those environments. Avoid assuming the local profile is available to the job.

Common errors and fixes

Symptom or check	What to inspect	Next step
The error only says “authentication failed”	The full AWS SDK error and the operation that failed	Do not infer a root cause from the short phrase. Obtain the complete error and use it to distinguish credential, permission, bucket, and client-configuration checks.
Reg-suit points at an unexpected bucket	`bucketName`, environment interpolation, and the job’s environment	Correct the value supplied to the Reg-suit process and verify it resolves to the intended bucket.
A local run works but CI fails	The identity and configuration available to the CI step	Verify the job’s effective identity and configuration with the platform’s safe inspection tools; do not assume the local default profile is used.
The error names a denied S3 operation	The effective identity policy and applicable bucket access rules for that operation	Compare the operation with the plugin’s documented action list and correct the specific missing or mismatched rule.
The project customizes `sdkOptions`	The effective options passed to the S3 client	Check them against the intended environment. Use the full error before attributing the failure to an option.
The error output contains credentials	CI log masking and diagnostic output	Redact secret values, avoid dumping credential environments, and retain only safe identity and error details.

Reliability, performance, and cost considerations

Reg-suit’s S3 publisher is part of the snapshot comparison workflow: it fetches prior snapshot images and writes current snapshots and reports. A failure to access the configured bucket can prevent that workflow from completing. The cited sources provide no benchmark or cost figure for this failure scenario, so use your own job logs and AWS account information to assess impact.

For a reliable diagnosis, record the operation, the effective non-secret identity context, the resolved bucket, and the complete error. Re-check these facts after changing credentials or access rules; do not use successful execution under a different local identity as proof that CI is fixed.

Or skip the browser setup

For a separate task—capturing website screenshots—ScreenshotNeo is a website screenshot API and MCP server for developers. It does not configure or repair Reg-suit or S3 access. One GET request can return an image or PDF; here is the documented cURL pattern for a WebP capture:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Does “authentication failed” identify a specific AWS cause?

No. The cited Reg-suit documentation does not associate that exact phrase with one confirmed cause. Diagnose from the complete error and the operation that failed.

Must I use access keys in CI?

The Reg-suit demo illustrates environment variables and a default shared credentials profile. It does not require one credential method for all CI environments. Verify the identity your job actually uses.

Should I switch Reg-suit from S3 to another storage provider?

The project documentation lists other publisher options, including Google Cloud Storage, but changing providers is not a diagnostic fix for an S3 identity or configuration failure. First identify the cause in the current workflow.

Share the Reg-suit configuration with secrets removed, the operation and complete redacted error, the resolved bucket name if safe to disclose, and whether the job runs locally or in CI. Never include secret values.