Troubleshooting

Troubleshooting Overview

Problems are a normal part of working with Git, GitHub, and deployment platforms. The important skill is learning how to identify where the problem occurred before trying to fix it.

A problem can usually be located in one of four areas:

Wrong Branch

One of the most common Git mistakes is making changes while working on a different branch than the one you intended to use.

Check the current branch

Before making changes, check which branch is currently active.

git branch

Git marks the current branch with an asterisk.

* feature/menu
main

Switch to the correct branch

If you are on the wrong branch, switch to the branch where the work belongs.

git switch main

Or, when working on a feature:

git switch feature/menu

Safe habit

git status
git branch
git switch feature/menu

Make checking the current branch part of your normal workflow before starting feature work.

Uncommitted Changes

Uncommitted changes are modifications in your working directory that have not yet been recorded in a Git commit.

Check what changed

Start by checking the repository status.

git status

Git will show modified files, staged files, and untracked files.

Review the changes

Before committing, inspect the actual changes.

git diff

Stage the changes

Once you are satisfied with the changes, stage them for the next commit.

git add .

Then check what is staged:

git diff –staged

Commit the changes

git commit -m “Describe the change”

If you are not ready to commit

There is no requirement to commit every change immediately. You can leave the changes in your working directory and continue working on them.

Quick Reference

Push Rejected

A push can be rejected when the remote GitHub repository contains commits that are not present in your local branch, or when the remote branch has changed since your last pull.

Check the current branch

First confirm that you are working on the branch you intend to push.

git branch
git status

Typical rejection message

! [rejected]        main -> main
error: failed to push some refs

One common reason is that the remote branch contains commits that your local branch does not have.

Get the latest remote changes

First download and integrate the latest changes from the remote branch.

git pull

If Git can integrate the changes automatically, you can then try the push again.

git push

If a conflict occurs

Sometimes the remote changes and your local changes cannot be combined automatically. Git will report the conflicting files.

git status

Resolve the conflicts, stage the resolved files, and complete the required commit before pushing again.

Safe troubleshooting sequence

git status
git branch
git pull
git status
git push

Quick Reference

Pull Conflicts

A pull conflict can occur when your local changes and changes from the remote branch affect the same part of a file and Git cannot combine them automatically.

Start with git pull

git pull

If Git cannot automatically combine the changes, it reports a conflict and identifies the affected files.

Check the conflicted files

git status

Look for files marked as unmerged or conflicted.

Open the conflicted file

Git places conflict markers inside the file so you can see the competing versions.

<<<<<<< HEAD
Your local changes
=======
Changes from the remote branch
>>>>>>> origin/main

Resolve the conflict

Edit the file and decide which content should remain. You can keep the local version, the incoming version, or combine the two.

Remove all Git conflict markers from the final file.

Stage the resolved file

git add filename

Check the repository again:

git status

Complete the merge

Once all conflicts have been resolved and staged, complete the merge created by the pull.

git commit

Push the resolved changes

After the conflict has been resolved and the merge commit has been created, push the result to GitHub.

git push

If you want to cancel the pull

If you started a merge during the pull and decide that you do not want to continue, you can abort the merge.

git merge –abort

This returns the repository to the state it was in before the merge started.

Quick Reference

Merge Conflicts

A merge conflict occurs when Git cannot automatically combine changes from two branches. This commonly happens when both branches modify the same part of a file.

When does a merge conflict happen?

For example, you may have a feature branch containing changes to a section of index.html, while main has also changed that same section. When Git tries to combine the branches, it may need you to decide which version should remain.

Start by checking the status

git status

Git identifies the files that need conflict resolution.

Inspect the conflict

Open each conflicted file. Git marks the competing sections using conflict markers.

<<<<<<< HEAD
Version from the current branch
=======
Version from the other branch
>>>>>>> feature/menu

Choose the final content

Edit the file and decide what the final version should contain. You can keep one version or combine both versions when appropriate.

Remove the conflict markers after resolving the content.

Stage the resolved file

git add filename

Then verify that Git considers the conflict resolved.

git status

Complete the merge

git commit

Git creates the merge commit after the conflicts have been resolved and the affected files have been staged.

Push the result

If the merge is being completed on a branch connected to GitHub, push the completed merge.

git push

Cancel the merge

If you started a merge but decide that you do not want to continue, you can abort the merge.

git merge –abort

Quick Reference

Cloudflare Build Failure

A Cloudflare Pages deployment can fail during the build process even when the code works correctly on your local computer.

Check the deployment log

Start by opening the failed deployment in Cloudflare Pages and reviewing its build log.

The build log usually contains the command that failed and an error message explaining what Cloudflare could not complete.

Check the deployment branch

Make sure Cloudflare is deploying the branch you intended to deploy.

git branch
git status

For example, a feature branch should normally create a preview deployment, while your configured production branch is used for production deployment.

Check the latest commit

Confirm that the code containing your latest changes was actually committed and pushed.

git log --oneline
git status
git push

Common things to check

Compare local and deployed builds

If the project builds successfully on your computer but fails on Cloudflare, compare the local build process with the build configuration used by Cloudflare.

Run the project’s build command locally, when applicable, and check whether the same error appears.

After fixing the problem

Commit the fix and push it to GitHub.

git add .
git commit -m "Fix deployment build"
git push

Cloudflare Pages can then create a new deployment from the updated commit.

Preview Not Updated

Sometimes you push new changes to a feature branch but the Cloudflare Pages preview does not appear to contain those changes.

Check the branch

First confirm that your local changes are on the branch that Cloudflare is expected to deploy.

git branch
git status

Check the latest commit

Confirm that your changes were actually committed.

git log –oneline

The latest commit should contain the changes you expect to see in the preview.

Check that the commit was pushed

git push

A commit that exists only on your computer cannot trigger a GitHub-connected Cloudflare deployment.

Check GitHub

Open the repository on GitHub and select the feature branch. Confirm that the latest commit and changed files are visible there.

Local changes
  ↓

Commit
↓
Push
↓
GitHub branch
↓
Cloudflare preview deployment

Check the Cloudflare deployment

Open the relevant preview deployment in Cloudflare Pages and check which commit the deployment was created from.

If the deployment corresponds to an older commit, check whether the latest push was received and whether a new deployment was created.

Check the preview URL

Make sure you are opening the preview deployment associated with the current branch and deployment.

If multiple preview deployments exist, an older preview URL may still display the previous version of the site.

Safe troubleshooting sequence

git status
git log --oneline
git push

Then verify, in order:

1. The correct branch contains the changes.
2. The changes are committed.
3. The commit has been pushed to GitHub.
4. Cloudflare created a deployment for that commit.
5. You are viewing the correct preview deployment.

Production Not Updated

Sometimes a change has been merged into the production branch, but the live website still appears to show the previous version.

Check the production branch

First confirm that the change was actually merged into the branch configured for production deployment.

git switch main
git pull
git log --oneline

The latest production commit should appear in the local main branch.

Check GitHub

Open the repository on GitHub and confirm that the expected Pull Request was merged into main.

The latest commit on main should contain the changes you expect to see in production.

Check the Cloudflare deployment

Open the Cloudflare Pages project and inspect the latest production deployment.

Confirm that the deployment was created from the expected production branch and commit.

Check the deployment status

A deployment may still be building or may have failed. Check its status and open the deployment log if necessary.

Verify the production URL

Once Cloudflare shows a successful production deployment, open the production website and verify the change.

If the deployment contains the new code but the browser still appears to show the previous version, perform a normal browser refresh and verify that you are visiting the correct production URL.

Safe troubleshooting sequence

git switch main
git pull
git log --oneline

Then verify the deployment chain:

1. The Pull Request was merged into main.

2. GitHub shows the expected commit on main.

3. Cloudflare created a production deployment for that commit.
4. The deployment completed successfully.
5. The production URL displays the expected changes.

Feature branch
    ↓

Pull Request
↓
main
↓
Cloudflare production deployment
↓
Production website

Quick Reference