Troubleshooting¶
Authentication Errors¶
GitHub¶
Azure DevOps¶
GitLab¶
# Check authentication status
glab auth status
# Re-authenticate if needed
glab auth login
# For self-hosted instances
glab auth login --hostname gitlab.example.com
Permission Denied¶
- Ensure your token has write access to the target repositories
- For GitHub, a classic token needs the
reposcope, plusworkflowto push files under.github/workflows/ - For Azure DevOps, ensure the user/service account has "Contribute to pull requests" permission
- For GitLab, ensure the user has at least "Developer" role on the project
GitHub Host Not Allowed¶
If a repo on a GitHub Enterprise Server host fails with "is not in XFG_ALLOWED_GITHUB_HOSTS", xfg refuses to send GitHub credentials to that host. Only github.com is trusted by default:
Entries are plain hostnames, with no scheme, port, path or IP address. Also list the host in githubHosts in the config. See GitHub Enterprise Server.
Branch Already Exists¶
The tool uses a fresh-start approach: it closes any existing PR on the branch and deletes the branch before creating a new one. This ensures each sync attempt is isolated and avoids merge conflicts from stale branches.
If you see issues with stale branches:
Missing Environment Variables¶
If you see "Missing required environment variable" errors:
# Set the variable before running
export MY_VAR=value
xfg sync --config ./config.yaml
# Or use default values in config
# ${MY_VAR:-default-value}
Network/Proxy Issues¶
If cloning fails behind a corporate proxy:
# Configure git proxy
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080
Debug Output¶
Set XFG_DEBUG (or DEBUG) to any non-empty value to print [debug] lines for the steps xfg runs:
Transient Network Errors¶
The tool automatically retries transient errors (timeouts, connection resets, rate limits) with exponential backoff. By default, it retries 3 times before failing.
# Increase retries for unreliable networks
xfg sync --config ./config.yaml --retries 5
# Disable retries
xfg sync --config ./config.yaml --retries 0
Permanent errors (authentication failures, permission denied, repository not found) are not retried.