My first production deploy took 6 hours instead of 30 minutes. Not because deployment is hard - because I assumed things would "just work." They didn't. Here are the five issues that cost me the most time.
1. DNS Propagation Isn't Instant
I pointed my domain to Vercel and immediately refreshed. Blank page. Panic.
What happened: DNS changes can take up to 48 hours to propagate globally, though it's usually 15—0 minutes.
Fix: Use dig yourdomain.com or an online DNS checker before assuming something is broken. Deploy to the platform's default URL first, then switch DNS.
2. Environment Variables Don't Transfer
My app worked locally. In production, the API returned 401 on every request.
What happened: .env files are gitignored (correctly). I forgot to set them in the hosting dashboard.
Fix: Maintain a .env.example file and a deployment checklist:
# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_SITE_URL=3. Mixed Content (HTTP vs HTTPS)
Images loaded on localhost but broke in production. Browser console screamed about mixed content.
What happened: Some asset URLs were hardcoded as http:// while the site served over HTTPS.
Fix: Always use relative paths or protocol-relative URLs. Better yet, use //-free paths like /images/photo.jpg.
4. Build Command Mismatch
Deploy succeeded. Site showed the default "Hello World" page.
What happened: The platform's default build command didn't match my project. It built successfully but output to the wrong directory.
Fix: Explicitly set build command and output directory in your hosting config:
# vercel.json or platform settings
{
"buildCommand": "npm run build",
"outputDirectory": "dist"
}5. Caching Old Assets
I deployed a CSS fix. My phone still showed the broken layout. Desktop was fine.
What happened: CDN and browser cache served stale assets.
Fix: Use cache-busting (hashed filenames in build output), and hard-refresh during testing (Ctrl+Shift+R). Most modern bundlers handle this automatically - if yours doesn't, that's a red flag.
My Deployment Checklist
- Test on platform's preview URL before touching DNS
- Copy all env vars to hosting dashboard
- Verify build command and output directory
- Check browser console for mixed content errors
- Test on mobile after DNS propagates
Deploy early, deploy often. The first deploy should happen on day one, not launch day.