Introduction

Recently, I learned an important lesson about AWS infrastructure that I wish I had known earlier. My project manager renamed a subdomain in Route 53, and suddenly our API was returning 404 errors. What seemed like a simple DNS change turned into a multi-hour debugging session that taught me how AWS App Runner custom domains actually work.

If you're using AWS App Runner and thinking about changing your API's subdomain, this post will save you hours of frustration.

The Problem

We had an API running on AWS App Runner, accessible via api.example.com. For security reasons, my project manager wanted to rename the subdomain to something less obvious. She went into Route 53 and changed the DNS record to point new.example.com to our App Runner service.

Simple enough, right? Wrong.

After the change, requests to https://new.example.com/path returned a 404 Not Found error. The confusing part? The DNS was resolving correctly—we could see traffic reaching the App Runner service. So why the 404?

Understanding the Root Cause

Here's what I didn't understand initially: Route 53 and App Runner are separate systems that need to be configured independently.

When you create a custom domain for App Runner, two things happen:

1. Route 53 handles DNS resolution (directing traffic to the right server)
2. App Runner handles domain recognition and SSL certificates (accepting and securing that traffic)

My PM had updated Route 53, but App Runner still only recognized api.examplt.com. When requests came in for new.example.com, App Runner said, "I don't know this domain" and returned a 404.

The Solution: Linking Custom Domains in App Runner

To fix this, I needed to add the new domain to App Runner's custom domains list. Here's the step-by-step process:

Step 1: Access App Runner Custom Domains

1. Go to AWS Console → App Runner
2. Click on your service
3. Navigate to the Custom domains tab
4. Click "Link domain"

Step 2: Add Your New Domain

1. Select your domain registrar (Route 53 or Non-Amazon)
2. Enter your domain name (e.g., new.example.com)
3. Click "Link domain"

Step 3: Configure DNS Validation Records

This is where it gets tricky. App Runner will display CNAME records that must be added to Route 53 for SSL certificate validation. These records look something like:

Record Name: _24f08242240de2268422c8e8d8226f81.new.example.com
Value: _40100f4010g1212c26126f10gbf24e45.kleeaautan.acm-validations.aws.

Important: When adding these to Route 53, you only enter the part before your domain. Route 53 automatically appends your domain name. So you'd enter:

_24f08242240de2268422c8e8d8226f81.new

NOT:

_24f08242240de2268422c8e8d8226f81.new.example.com

This was the source of several errors during my troubleshooting!

Step 4: Wait for Validation

Once the CNAME records are correctly added, AWS will validate your domain ownership and issue an SSL certificate. This typically takes 5-30 minutes, though it can take up to 24-48 hours in rare cases.

You can monitor progress by:

• Refreshing the App Runner custom domains page
• Using nslookup to verify DNS propagation:

nslookup -type=CNAME _24f08242240de2268422c8e8d8226f81.new.example.com

Step 5: Verify Success

When the status changes from "Pending certificate DNS validation" to "Active", your new domain is ready! Test it:

curl https://new.example.com/path

Common Pitfalls to Avoid

During this process, I encountered several issues that cost me time:

1. Wrong Record Type

Make sure you create CNAME records, not A or TXT records. The validation will fail with the wrong type.

2. Incomplete Record Names

The validation record names are long strings. Copy them carefully! Missing characters will cause validation to fail.

3. Leading Spaces

An invisible space at the beginning of your record name will prevent DNS resolution entirely. Always double-check for hidden characters.

4. Duplicate Domain Suffixes

Remember: Route 53 auto-appends your domain. Entering subdomain.yourdomain.com in Route 53 creates subdomain.yourdomain.com.yourdomain.com—not what you want!

Key Takeaways

1. DNS changes and application configuration are separate concerns. Updating Route 53 doesn't automatically update your App Runner service.

2. App Runner manages its own SSL certificates. You can't reuse certificates from other domains—each custom domain needs its own validation.

3. Custom domains can't be renamed. You must add new domains and optionally remove old ones.

4. Patience is key. DNS propagation and certificate validation take time. Use nslookup to monitor progress rather than constantly refreshing.

5. Details matter. A single typo, missing character, or extra space can cause hours of debugging.

Conclusion

What seemed like a simple subdomain rename turned into a valuable lesson about AWS architecture. The separation of concerns between Route 53 (DNS) and App Runner (application hosting) makes sense from a security and modularity standpoint, but it's not immediately obvious to beginners.

If you're planning to change your App Runner custom domain, remember: Route 53 handles where traffic goes, but App Runner decides whether to accept it. Configure both, and you'll avoid the 404 headache I experienced.

Have you encountered similar AWS configuration challenges? I'd love to hear about your experiences in the comments below!

This post is based on my real-world experience debugging a domain configuration issue.