Deployment module
Testing and Troubleshooting a Live Website
Diagnose homepage, CSS, image, 404, white screen, caching, build, DNS, and routing problems using evidence instead of random changes.
Learning Objectives
By the end of this lesson, you'll be able to:
- Diagnose deployment problems using symptoms and evidence
- Use browser developer tools, network requests and deployment logs
- Fix one meaningful issue at a time
- Avoid random changes before reading the first useful error
Why This Matters:
Troubleshooting is calmer when you read the system before changing the system.
Troubleshooting Workflow
Confirm the live URL
-> Check the deployment status
-> Open browser developer tools
-> Read the first meaningful error
-> Check paths and filenames
-> Check build and hosting logs
-> Fix one issue
-> Redeploy and verifyResist the urge to change things randomly. The first real error is often the site trying to tell you exactly where to look.
Good troubleshooting separates symptoms from causes. "The site is broken" is too broad. "The homepage loads but the CSS file returns 404" is useful. "The Vite JavaScript file is requested from the wrong base path" is even better. Each observation narrows the system.
Common Live Website Problems
Homepage does not load
Likely causes: No index.html, incorrect public folder, files nested one level too deep, DNS not connected, or deployment failed.
Checks: Confirm the live URL, public web root, deployment status, DNS connection and whether index.html is directly inside the served folder.
Possible fix: Move files to the correct public folder, wait for DNS/deployment completion where appropriate, then test the live URL again.
CSS does not load
Likely causes: Incorrect path, case mismatch, missing uploaded file, browser cache, or a server MIME issue.
Checks: Open DevTools Network, look for the CSS request, check status code, path, filename and capitalization.
Possible fix: Correct the href, upload the missing file, match case exactly and hard refresh or test in a private window.
Images are missing
Likely causes: Wrong filename, uppercase/lowercase mismatch, wrong extension, local-only path, or asset not included in the build.
Checks: Inspect the image URL in DevTools and compare it with the actual file in the deployed folder.
Possible fix: Use project-relative paths, simple lowercase filenames and redeploy the missing assets or rebuilt output.
Website works locally but not online
Likely causes: Missing build step, incorrect base path, missing files, unsupported server behaviour, SPA routing, or environment variables.
Checks: Check build output, host settings, console errors, network errors and deployment logs.
Possible fix: Build the project, deploy the correct output folder, configure routing/base path and add required environment variables.
Updates do not appear
Likely causes: Browser cache, CDN cache, deployment still processing, wrong branch, wrong hosting directory, or edited source not included in build.
Checks: Check deployment timestamp, branch, build log, uploaded directory and private-window result.
Possible fix: Redeploy the correct source/output, clear or wait for caches, and confirm you are testing the right live URL.
White screen
Likely causes: Missing JavaScript files, runtime errors, incorrect base path, missing environment variables, or broken client-side routing.
Checks: Open browser console, Network panel and deployment logs. Read the first meaningful error.
Possible fix: Fix the first error, rebuild, redeploy and verify. Do not change five things at once.
404 errors
Likely causes: Missing files, wrong URL, case-sensitive paths, nested directories, SPA fallback routing, or wrong deployment directory.
Checks: Compare requested URL with deployed files and check host routing/fallback settings.
Possible fix: Correct the path, move files, configure SPA fallback where needed and redeploy.
What to Inspect
- browser console errors
- Network panel failed requests and status codes
- deployment logs from the hosting provider
- missing JavaScript, CSS and image files
- base path and environment variable errors
- case-sensitive file paths and nested folders
Case Study: CSS Missing After Upload
Symptom: the homepage text appears, but it looks unstyled. In DevTools, the Network panel shows css/styles.css returning 404. First check whether the file was uploaded. Then check exact folder and filename case. If the file is really named CSS/Styles.css, rename files and references consistently, upload again and hard-refresh the page.
Case Study: Vite White Screen
Symptom: the deployed page is blank. The console shows a missing JavaScript bundle or a runtime error. Check the deployment log for a failed build, confirm the output directory is dist, check base path configuration, and confirm required environment variables are defined on the hosting platform.
Troubleshooting Knowledge Check
Before moving forward, can you answer these?
- Why should students read the first meaningful error before changing files?
- What should be checked when images work locally but not online?
- What panels in browser developer tools are most useful for deployment issues?
Check Your Answers
- It identifies the part of the system that is failing and prevents random changes.
- Filename case, extension, path, upload/build inclusion, and whether the reference points outside the project.
- The Console for runtime errors and the Network panel for missing files, status codes and incorrect paths.
How confident are you with this concept?
Still confused | Getting there | Got it | Could explain it to a friend
Ready for the Next Deployment Step
Key Takeaways:
- Deployment is a publishing workflow, not just a button.
- The live URL is where deployment evidence is gathered.
- The right hosting path depends on files, update workflow, support needs and ownership.
- Troubleshooting starts with the first meaningful error.
Learning Objectives Review:
Look back at what you set out to learn. Can you now:
- Diagnose homepage, CSS, image, 404, white screen, caching, build, DNS, and routing problems using evidence instead of random changes. Check!
If you can name which part of the system you are changing, test the live result and record the outcome, deployment is becoming a repeatable workflow.
Think & Reflect:
Deployment evidence
- What would prove this site works for someone else?
Next action
- What should be recorded so this deployment can be repeated later?
Looking Ahead:
Next: continue with Continuous Improvement and Deployment Workflows.
Recommended Next Steps
Continue Learning
Ready to move forward? Continue with the next tutorial in this series:
Continuous Improvement and Deployment WorkflowsRelated Topics
Explore these related tutorials to expand your knowledge: