When Production Lies: Debugging File Conflicts in Deployment

Friday, July 25, 2025 • 11:12 GMT+7

Sometimes production deployments fail in the most unexpected ways. Today’s 17-minute debugging session is a perfect example of how a simple file conflict can completely break user experience - showing users an entirely different application than intended.

The Crisis

Expected: FloodBoy blockchain page with colorful sensor cards
Reality: IoT Factory Dashboard with contract interfaces

Users visiting https://blockchain.floodboy.online/blockchain were seeing the wrong application entirely. Not a styling issue, not a data problem - a completely different interface.

The Investigation

Step 1: Deployment Pipeline Check

First assumption: deployment sync issue. The code was merged, the PR was successful, but production wasn’t reflecting changes.

# Everything looked correct:
✅ PR #107 merged successfully  
✅ Main branch updated
✅ Git push completed
❌ Production still showing wrong content

Step 2: Manual Deployment Attempt

Tried forcing a manual deployment through Wrangler:

npx wrangler deploy
# ❌ ERROR: More than one account available 
# Need CLOUDFLARE_ACCOUNT_ID configuration

Lesson: Deployment access configuration matters. When production is broken, you need immediate deployment capabilities.

Step 3: Build Verification

The build was successful - all files generated correctly:

✓ Completed in 2.75s
[build] Complete!
# All routes prerendered successfully
# No TypeScript errors
# No missing dependencies

This ruled out build issues and pointed to a deployment/routing problem.

Step 4: The Discovery

Finally, checking git status revealed the smoking gun:

Changes not staged for commit:
    deleted:    public/blockchain.html
Untracked files:
    public/blockchain1.html

The culprit: A file rename conflict. The critical blockchain.html file was deleted and renamed to blockchain1.html.

The Root Cause

This wasn’t just a rename - it was a routing break. The production deployment was looking for blockchain.html but finding either nothing or an old cached version, causing it to fall back to a different page entirely.

Why This Happened

1. Merge Conflicts: During branch merges, file conflicts can result in unexpected renames
2. Git Rename Detection: Git detected the file as renamed rather than modified
3. Deployment Sync: Production deployments rely on specific file paths
4. Routing Dependencies: The /blockchain route expected blockchain.html to exist

The Fix Attempts

Attempt 1: Deployment Comment Trigger

Added a comment to force a fresh deployment:

---
// FloodBoy Blockchain IoT Sensor Dashboard - Production Deploy 2025-07-25
import BaseHead from '../components/BaseHead.astro';

Result: Triggered deployment but didn’t address the file structure issue.

Attempt 2: File Structure Restoration

Committed the file rename to acknowledge the new structure:

git add -A
git commit -m "fix: Restore blockchain.html file structure"
git push origin main

Result: Deployment triggered, but the fundamental routing issue likely persists.

Technical Insights

File Routing in Astro/Cloudflare

Modern web frameworks rely heavily on file-based routing. When critical files are renamed or deleted:

1. Route Resolution Fails: The /blockchain route can’t find its corresponding file
2. Fallback Behavior: Framework serves alternative content (wrong page)
3. Cache Confusion: CDN/deployment systems may serve stale content
4. Production Discrepancy: Local dev works, production fails

The Deployment Pipeline

Local Dev (✅) → Git Push (✅) → Build (✅) → Deploy (❌) → Production (❌)

The failure point was between build and deployment - the build succeeded, but deployment couldn’t properly route the built files.

Prevention Strategies

1. Pre-deployment Verification

# Always verify critical files exist
ls -la public/blockchain*.html
# Check for unexpected renames
git status --porcelain

2. Deployment Access Configuration

# Set up proper deployment credentials
export CLOUDFLARE_ACCOUNT_ID="your-account-id"
# Test deployment access before emergencies

3. Production Monitoring

• Automated checks for critical page content
• Deployment verification scripts
• Rollback procedures for failed deployments

4. File Structure Integrity

• Branch merge reviews should check for file renames
• Critical files should have protection policies
• Deployment scripts should validate file existence

The Bigger Picture

This incident highlights a fundamental challenge in modern web development: the gap between successful builds and working deployments.

• ✅ Code Quality: TypeScript passes, linting passes, builds succeed
• ✅ Git Operations: Merges complete, pushes succeed
• ❌ User Experience: Production serves wrong content entirely

The tools and processes that ensure code quality don’t necessarily ensure deployment quality.

Lessons for Production Systems

1. File-based Routing is Fragile

When your routing depends on specific files existing at specific paths, any disruption to that structure can break user experience entirely.

2. Deployment != Build Success

A successful build doesn’t guarantee a successful deployment. Separate verification is needed.

3. Production Debugging Requires Access

When production breaks, you need immediate deployment access. Configuration delays cost user experience.

4. Conflicts Cascade

A simple file rename can cascade into routing failures, cache issues, and completely broken user experience.

The Resolution Status

As of this writing (11:12 GMT+7), the production issue remains unresolved despite multiple fix attempts. The file structure has been corrected, but the deployment pipeline may require additional intervention.

Next Steps:

• Manual Cloudflare configuration
• Direct deployment verification
• Production routing investigation
• Rollback procedure implementation

Key Takeaways

1. Production issues require systematic debugging - assumptions about deployment success can be wrong
2. File conflicts have deployment consequences - what looks minor in git can break production entirely
3. Deployment access is critical - when production breaks, every minute matters
4. Verification processes matter - successful builds don’t guarantee working deployments

This debugging session reminds us that production deployment is as much about file structure integrity as it is about code quality. Sometimes the smallest conflicts have the biggest consequences.

---

Status: Production deployment issue ongoing - file structure corrected, deployment pipeline investigation continues.