Skip to content

Troubleshooting

Authentication Errors

GitHub

# Check authentication status
gh auth status

# Re-authenticate if needed
gh auth login

Azure DevOps

# Check authentication status
az account show

# Re-authenticate if needed
az login

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 repo scope, plus workflow to 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:

# Comma- or space-separated hostnames
export XFG_ALLOWED_GITHUB_HOSTS="github.mycompany.com"

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:

# Manually delete the remote branch if needed
git push origin --delete chore/sync-config

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:

XFG_DEBUG=1 xfg sync --config ./config.yaml

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.