How to fix remote: error: pre-receive hook declined in Git

What this error means

This error indicates that a pre-receive hook on the remote Git server has rejected your push operation. Pre-receive hooks are server-side scripts that run before any refs are updated, allowing administrators to enforce repository policies. When you push commits to a remote repository, the server can execute custom scripts to validate the incoming changes. If the validation fails, the server returns this error and refuses to accept the push. The hook itself does not modify anything on the server - it simply accepts or rejects the push based on predefined rules. Common scenarios where this error appears include: 1. **Protected branch enforcement**: Many Git hosting platforms (GitHub, GitLab, Bitbucket) implement branch protection rules as pre-receive hooks. Attempting to push directly to a protected branch without proper permissions triggers this error. 2. **Push rules validation**: Organizations configure push rules to enforce commit message formats (e.g., requiring JIRA ticket numbers), file size limits, author email verification, or other compliance requirements. 3. **Permission issues**: You may lack the necessary role (e.g., Maintainer vs Developer) to push to certain branches. The error message itself is intentionally generic. The actual reason for rejection is usually provided in lines prefixed with "remote:" that appear before the hook declined message. Always read the full error output carefully to understand the specific violation.

Typical symptoms

• Git push command fails with 'remote: error: pre-receive hook declined' message
• Force push (git push --force) is rejected with this error
• Push to specific branches like main or master fails while other branches work
• CI/CD pipelines fail during the git push step
• Initial push to a new repository is rejected
• Merge commits fail to push after rebasing or amending
• Push works for some team members but not others

Common causes

1. Pushing to a protected branch without required permissions (most common)
2. Insufficient role assignment (Developer instead of Maintainer on GitLab)
3. Commit message does not follow required format (e.g., missing JIRA ticket number)
4. File size exceeds repository limit (typically 100MB on GitHub, configurable on GitLab)
5. Author email does not match verified emails on the platform
6. Attempting force push when force pushes are disabled
7. Branch requires pull/merge request workflow instead of direct push
8. Non-fast-forward push when history rewriting is blocked
9. Custom server hook script validation failure
10. Git hosting service experiencing temporary issues

How to fix "remote: error: pre-receive hook declined"

# Example output with context:
remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Required status check "ci/tests" is expected.
remote: error: pre-receive hook declined

# Create a new branch from your current changes
git checkout -b feature/my-changes

# Push the feature branch
git push -u origin feature/my-changes

# Then create a PR/MR through the web interface

# Test your SSH connection to verify you're using the right account
ssh -T git@github.com
ssh -T git@gitlab.com

# Check the remote URL
git remote -v

# Amend the most recent commit message
git commit --amend -m "JIRA-123: Add new feature"

# Interactive rebase to edit multiple commits
git rebase -i HEAD~3

# In the editor, change 'pick' to 'reword' for commits needing new messages
# Save and follow prompts to enter new messages

git push --force-with-lease origin your-branch

# Find large files in your repository
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print $3, $4}' | sort -rn | head -20

# Remove a large file from the last commit
git reset --soft HEAD~1
git rm --cached large-file.zip
git commit -m "Your commit message"

# Remove from entire history (use with caution)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch path/to/large-file.zip" \
  --prune-empty --tag-name-filter cat -- --all

# Install and configure Git LFS
git lfs install
git lfs track "*.zip"
git add .gitattributes

# Fetch latest changes
git fetch origin

# Rebase your changes on top of remote
git pull --rebase origin main

# Or merge if you prefer
git pull origin main

# Then push
git push origin main

# After resolving conflicts
git add .
git rebase --continue

# Then push
git push origin main

# Check your Git email configuration
git config user.email

# Check the email in your commits
git log --format='%ae' -1

# Update your Git email to match your account
git config --global user.email "your-verified-email@example.com"

# Amend the last commit with correct email
git commit --amend --reset-author --no-edit

# For multiple commits, use interactive rebase
git rebase -i HEAD~5 --exec "git commit --amend --reset-author --no-edit"

# Wait a few minutes, then retry
git push origin main

# Test SSH connectivity
ssh -T git@github.com

# Test HTTPS connectivity
curl -I https://github.com

Advanced notes

<old-sha> <new-sha> <ref-name>

# Common push rules that can cause this error:
- Commit message regex (e.g., must contain ticket number)
- Author email regex (must match company domain)
- Branch name regex
- File name blacklist
- Maximum file size
- Prevent secrets (blocks AWS keys, etc.)
- Reject unsigned commits

# View hook scripts on the server
ls -la /path/to/repo.git/hooks/

# Check hook logs (varies by platform)
# GitLab: /var/log/gitlab/gitaly/current
# GitHub Enterprise: /var/log/github/enterprise/unicorn.log

# Test hook locally (on server)
echo "old-sha new-sha refs/heads/main" | ./hooks/pre-receive

# Instead of --force, use --force-with-lease for safer overwrites
git push --force-with-lease origin feature-branch

# This fails if someone else pushed in the meantime

Frequently asked questions

What does "remote: error: pre-receive hook declined" mean?

This error indicates that a pre-receive hook on the remote Git server has rejected your push operation. Pre-receive hooks are server-side scripts that run before any refs are updated, allowing administrators to enforce repository policies. When you push commits to a remote repository, the server can execute custom scripts to validate the incoming changes.

How do I fix "remote: error: pre-receive hook declined"?

Fix Git push rejected by "pre-receive hook declined" - protected branch, missing permissions, or commit policy. How to find the rule and push.

What causes "remote: error: pre-receive hook declined"?

Pushing to a protected branch without required permissions (most common) Insufficient role assignment (Developer instead of Maintainer on GitLab) Commit message does not follow required format (e.g., missing JIRA ticket number)

Is the "remote: error: pre-receive hook declined" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• fatal: protocol error: bad pack header

  Protocol error: bad pack header

  MEDIUM

• error: pre-rebase hook exited with error code 1

  How to fix pre-rebase hook failure in Git

  LOW

• fatal: unable to negotiate: protocol error

  How to fix 'unable to negotiate: protocol error' in Git

  MEDIUM

• hint: The pre-commit hook was ignored because it's not set as executable

  How to fix 'pre-commit hook was ignored because it's not set as executable' in Git

  LOW

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 💬
  Stack Overflow - Git pre-receive hook declined(Stack Overflow)
• 📝
  GeeksforGeeks - How to fix pre-receive hook declined
• 📖
  GitLab - Server hooks documentation(Official Docs)
• 💬
  Stack Overflow - GitLab pre-receive hook declined(Stack Overflow)
• 📝
  Tim Mouskhelichvili - Git pre-receive hook declined