AWS preflight verification
What AWS BYO S3 preflight checks, what each failure means, and how to resolve it.
When you add or update an AWS BYO S3 destination, run preflight verification before any backup can be scheduled against it. Preflight is a series of probes that confirm every required S3 and IAM capability is in place.
For MinIO, GCS S3-compatible, Wasabi, and Backblaze B2 destinations, use the provider-specific destination guide. Those providers share the destination workflow but differ in retention semantics, public-access APIs, and which controls walwarden can verify directly.
Preflight also runs on a recurring schedule after a destination is active, so configuration drift is detected before it blocks a backup.
For AWS BYO S3, the destination role is intentionally backup-and-restore capable. Walwarden assumes the same external-ID-protected role when it writes backups, runs preflight, and signs restore GET URLs. A write-only role cannot be verified because restore would later fail to fetch the artifact. Least privilege is enforced by using a dedicated backup bucket and by the public-access block, TLS-only, external-ID, and Object Lock checks.
What preflight checks
| Check | Failure surface |
|---|---|
sts:AssumeRole with the configured role ARN and external ID | Role does not exist, external ID mismatch, or walwarden's account is not listed as a trusted principal |
s3:PutObject — write a probe object to the bucket | Missing PutObject permission, bucket does not exist, or bucket is in a different region than configured |
s3:GetObject — read the probe object back for restore | Missing GetObject permission; restore presigning would not be able to fetch artifacts |
s3:HeadObject — check object metadata | Missing HeadObject permission |
s3:PutObjectRetention — apply a GOVERNANCE retention hold | Missing PutObjectRetention permission, or Object Lock is not enabled on the bucket |
s3:GetObjectRetention — verify the retention hold | Missing GetObjectRetention permission |
| Public access block — confirm all four settings are enabled | Any setting is off |
| Bucket versioning — confirm versioning is enabled | Versioning is disabled (Object Lock requires it) |
| TLS enforcement — confirm the bucket policy denies non-TLS requests | Bucket policy missing or incomplete |
| Cleanup — delete the probe object | Missing DeleteObject permission |
What to do when preflight fails
sts:AssumeRole failed
The IAM role trust policy does not match. Most common causes:
- The external ID in the trust policy does not match the value walwarden issued. Copy the external ID directly from the walwarden dashboard destination page and re-create the trust policy. Do not modify the value.
- The trusted principal is wrong. It must be
arn:aws:iam::194343789105:root. - The role ARN was entered incorrectly in walwarden. Verify the ARN in the IAM console and update the destination.
Write probe object failed
The IAM role does not have s3:PutObject on the bucket, or the bucket name or region is wrong.
- Verify the bucket name in walwarden exactly matches the bucket name in the S3 console (case-sensitive).
- Verify the region matches.
- Open the IAM policy attached to the role and confirm
s3:PutObjectis listed with the correct bucket ARN.
Read probe object failed
The IAM role does not have s3:GetObject on the walwarden backup bucket. Add s3:GetObject for the dedicated bucket used by backup artifacts. Without it, preflight stays failed because restore URL signing uses this destination role to fetch the artifact.
PutObjectRetention failed
The IAM policy is missing s3:PutObjectRetention, or Object Lock is not enabled on the bucket.
- Add
s3:PutObjectRetentionto the policy from BYO AWS S3 step 3. - In the S3 console, go to the bucket Properties tab and confirm Object Lock is enabled. If it is not, you must create a new bucket — Object Lock cannot be enabled after creation.
Public access block failed
Go to the S3 bucket Permissions tab and confirm all four Block public access settings are checked.
Object Lock not in GOVERNANCE mode
If preflight reports that Object Lock is enabled but the mode is wrong, check the bucket's default retention settings. Walwarden requires GOVERNANCE mode. If the bucket was created with COMPLIANCE mode, create a new bucket.
Preflight passes but backups still fail
Preflight confirms IAM permissions and bucket configuration at a point in time. If an IAM policy is later modified or rotated, the next backup will fail even though the last preflight passed. Re-run preflight manually from the Destinations page after any IAM change.