This error occurs when Git cannot locate the osxkeychain credential helper on macOS. It typically happens when using Git GUI applications with bundled Git versions that cannot find the system credential helper, or when the credential helper is misconfigured.
The `credential-osxkeychain` error indicates that Git is configured to use the macOS Keychain credential helper, but it cannot find the helper executable. This helper is responsible for securely storing your Git credentials (usernames and passwords or tokens) in the macOS Keychain. When you perform Git operations that require authentication (push, pull, clone from private repos), Git looks for the credential helper specified in your configuration. If it's set to `osxkeychain` but the `git-credential-osxkeychain` binary isn't in Git's PATH, you'll see this error. This commonly happens in these scenarios: 1. **Different Git installations** - macOS has multiple ways to install Git (Xcode Command Line Tools, Homebrew, bundled with apps), and each may use different paths 2. **Git GUI applications** - Apps like GitHub Desktop, SourceTree, Fork, or Tower bundle their own Git version which may not include the system credential helper 3. **Misconfigured PATH** - The credential helper exists but isn't in a directory Git can find 4. **Missing installation** - The osxkeychain helper was never installed or was removed
First, identify which Git installation is active and verify the credential helper status:
# Check Git version and location
which git
git --version
# Check current credential helper configuration
git config --global credential.helper
git config --list | grep credential
# Check if osxkeychain helper exists
git credential-osxkeychain
# If it exists, it will wait for input (press Ctrl+C to exit)If git credential-osxkeychain returns the "not a git command" error, the helper is missing from your current Git installation.
The macOS Command Line Tools include the osxkeychain credential helper. Install or reinstall them:
# Install Command Line Tools (opens a dialog)
xcode-select --install
# If already installed, you can reinstall:
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
# Verify installation
xcode-select -p
# Should show: /Library/Developer/CommandLineToolsAfter installation, check if the credential helper is now available:
git credential-osxkeychain
# Should wait for input (press Ctrl+C)If you're using Homebrew Git, upgrading often resolves path issues:
# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install or upgrade Git
brew install git
# or
brew upgrade git
# Ensure Homebrew Git is used (add to ~/.zshrc or ~/.bash_profile)
export PATH="/opt/homebrew/bin:$PATH" # Apple Silicon
# or
export PATH="/usr/local/bin:$PATH" # Intel Mac
# Reload shell configuration
source ~/.zshrc
# or
source ~/.bash_profile
# Verify the new Git is being used
which git
git --versionHomebrew's Git typically includes the osxkeychain helper properly configured.
Many Git GUI applications bundle their own Git version. Configure them to use your system Git instead:
SourceTree:
1. Open SourceTree > Preferences (Cmd+,)
2. Go to the Git tab
3. Under "Git Version", select Use System Git
4. Restart SourceTree
Fork:
1. Open Fork > Preferences (Cmd+,)
2. Go to the Git tab
3. Under "Git Instance", select the system Git (usually /usr/bin/git or Homebrew path)
4. Restart Fork
Tower:
1. Open Tower > Preferences
2. Go to Git Config
3. Ensure it uses the system Git installation
GitHub Desktop:
GitHub Desktop typically uses its bundled Git. If issues persist, consider using the command line or switching to another GUI that allows system Git selection.
If the credential helper exists but your Git installation can't find it, create a symbolic link:
# Find where git-credential-osxkeychain is installed
find /usr -name "git-credential-osxkeychain" 2>/dev/null
find /Library -name "git-credential-osxkeychain" 2>/dev/null
find /opt -name "git-credential-osxkeychain" 2>/dev/null
# Common locations:
# /usr/local/git/bin/git-credential-osxkeychain
# /Library/Developer/CommandLineTools/usr/libexec/git-core/git-credential-osxkeychain
# /opt/homebrew/bin/git-credential-osxkeychain
# Create symbolic link to /usr/local/bin (commonly in PATH)
sudo ln -s /Library/Developer/CommandLineTools/usr/libexec/git-core/git-credential-osxkeychain /usr/local/bin/git-credential-osxkeychain
# Or link from Homebrew location
sudo ln -s /opt/homebrew/bin/git-credential-osxkeychain /usr/local/bin/git-credential-osxkeychainFor Git GUI applications with bundled Git:
# For GitHub Desktop (example)
ln -s /usr/local/bin/git-credential-osxkeychain "/Applications/GitHub Desktop.app/Contents/Resources/git/bin/git-credential-osxkeychain"
# For SourceTree
ln -s /usr/local/bin/git-credential-osxkeychain "/Applications/Sourcetree.app/Contents/Resources/git_local/bin/git-credential-osxkeychain"Reset and reconfigure the credential helper in your Git configuration:
# Remove any existing credential helper configuration
git config --global --unset-all credential.helper
# Configure osxkeychain as the credential helper
git config --global credential.helper osxkeychain
# Verify the configuration
git config --global credential.helper
# Should output: osxkeychain
# Test the helper
echo "protocol=https
host=github.com" | git credential-osxkeychain get
# If credentials exist, it will output them
# If not, it will output nothing (that's OK)If osxkeychain still doesn't work, try an alternative:
# Use the Git Credential Manager (recommended by GitHub)
brew install git-credential-manager
git config --global credential.helper manager
# Or use simple credential caching (temporary storage)
git config --global credential.helper cacheGitHub recommends Git Credential Manager (GCM) as the modern replacement for osxkeychain:
# Install Git Credential Manager via Homebrew
brew install git-credential-manager
# Configure Git to use GCM
git config --global credential.helper manager
# Verify installation
git credential-manager --versionBenefits of Git Credential Manager:
- Supports two-factor authentication (2FA)
- Works with GitHub, GitLab, Azure DevOps, Bitbucket
- Uses OAuth for secure browser-based authentication
- Cross-platform (also works on Windows and Linux)
After installation, the next time you push or pull, GCM will open a browser window for authentication if needed.
As an alternative to credential helpers, use SSH keys which don't require the osxkeychain helper:
# Check for existing SSH keys
ls -la ~/.ssh
# Generate a new SSH key (if needed)
ssh-keygen -t ed25519 -C "[email protected]"
# Press Enter to accept defaults, optionally set a passphrase
# Start the SSH agent and add your key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Add to macOS Keychain (so you don't need to re-enter passphrase)
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# Copy the public key
pbcopy < ~/.ssh/id_ed25519.pubAdd the key to your Git hosting service:
- GitHub: Settings > SSH and GPG keys > New SSH key
- GitLab: Preferences > SSH Keys
- Bitbucket: Personal settings > SSH keys
Update your repository remotes to use SSH:
# Check current remote
git remote -v
# Change from HTTPS to SSH
git remote set-url origin [email protected]:username/repo.git
# Test SSH connection
ssh -T [email protected]### Understanding macOS Git Installations
macOS can have multiple Git installations simultaneously:
| Source | Typical Path | Notes |
|--------|-------------|-------|
| Xcode CLT | /Library/Developer/CommandLineTools/usr/bin/git | Default for /usr/bin/git |
| Homebrew (ARM) | /opt/homebrew/bin/git | Apple Silicon Macs |
| Homebrew (Intel) | /usr/local/bin/git | Intel Macs |
| App Bundle | /Applications/[App].app/Contents/Resources/git | Isolated per app |
Check which one is active:
# Show all Git installations
which -a git
# Show which is first in PATH
which git### Credential Helper Locations
The git-credential-osxkeychain binary can be in various locations:
# List all possible locations
/usr/local/bin/git-credential-osxkeychain
/Library/Developer/CommandLineTools/usr/libexec/git-core/git-credential-osxkeychain
/opt/homebrew/bin/git-credential-osxkeychain
/opt/homebrew/libexec/git-core/git-credential-osxkeychain### Debugging Credential Helper Issues
# Enable Git credential debugging
GIT_TRACE=1 git push origin main
# More verbose debugging
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push origin main
# Check all credential-related config
git config --list --show-origin | grep credential
# Test credential helper directly
echo "protocol=https
host=github.com" | git credential fill### Keychain Access Troubleshooting
If credentials are corrupted in the Keychain:
1. Open Keychain Access (Spotlight > "Keychain Access")
2. Search for github.com (or your Git host)
3. Find entries labeled "Internet password"
4. Right-click and delete problematic entries
5. Re-authenticate on next Git operation
Via command line:
# Erase specific credentials
git credential-osxkeychain erase
host=github.com
protocol=https
# Press Enter twice
# For GitLab
git credential-osxkeychain erase
host=gitlab.com
protocol=https
# Press Enter twice### PATH Configuration for Multiple Git Versions
If you have multiple Git installations, ensure the correct one is first in your PATH:
# In ~/.zshrc or ~/.bash_profile
# Homebrew Git first (Apple Silicon)
export PATH="/opt/homebrew/bin:$PATH"
# Or Homebrew Git first (Intel)
export PATH="/usr/local/bin:$PATH"
# Then reload
source ~/.zshrc### CI/CD Considerations
For GitHub Actions on macOS runners:
- name: Configure Git credentials
run: |
git config --global credential.helper store
echo "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com" > ~/.git-credentialsOr use SSH:
- name: Setup SSH
uses: webfactory/[email protected]
with:
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}### Alternative Credential Helpers
If osxkeychain continues to cause issues, alternatives include:
# Git Credential Manager (recommended)
git config --global credential.helper manager
# Simple cache (credentials stored in memory for 15 minutes)
git config --global credential.helper cache
# Store in plain text file (less secure)
git config --global credential.helper store
# Specify cache timeout (1 hour)
git config --global credential.helper 'cache --timeout=3600'warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server