Preflight verification
What preflight checks, what each failure means, and how to resolve it.
When you add or update a destination, walwarden runs 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.
Preflight also runs on a recurring schedule after a destination is active, so configuration drift is detected before it blocks a backup.
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 test object to the bucket | Missing PutObject permission, bucket does not exist, or bucket is in a different region than configured |
s3:GetObject — read the test object back | Missing GetObject permission |
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 test 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 test 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.
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.