Troubleshooting
This guide helps you diagnose and fix common issues with recommit.
Cherry-Pick Issues
Cherry-Pick Not Triggered
Symptoms: You merged a PR but no cherry-pick tasks were created.
Check Repository is Enabled
- Go to Console → Repositories
- Verify your repository shows "Connected"
- If disabled, click to enable it
Check Roadmap is Linked
- Verify a Roadmap is linked to your repository
- If unlinked, link a Roadmap in the repository settings
Check Target Branches Exist
- Verify the branches in your Roadmap exist in GitHub
- Cherry-picks skip non-existent branches
Check PR Target Branch
- Verify the PR was merged to a branch in your Roadmap
- PRs merged to branches outside the Roadmap won't trigger cherry-picks
Check Subscription Status
- Go to Console → Billing
- Verify your subscription is active
- Expired subscriptions don't process cherry-picks
Cherry-Pick Failed
Symptoms: Cherry-pick task shows "Failed" status.
Common Causes:
| Cause | Solution |
|---|---|
| Merge conflicts | Resolve manually and push |
| Branch protection | Ensure GitHub App has bypass permissions |
| Missing branch | Create the target branch in GitHub |
| Permission error | Re-authorize the GitHub App |
Resolution Steps:
Check Error Details
- Go to Console → Cherry-picks
- Click on the failed task
- Review the error message
For Merge Conflicts
Conflicts require manual resolution:
# Clone and checkout the cherry-pick branch
git checkout cherry-kit/<pr-number>-<branch>
# Resolve conflicts
git mergetool
# Commit and push
git add .
git commit -m "resolve conflicts"
git pushFor Permission Errors
- Go to GitHub → Settings → Applications
- Find recommit.dev
- Review and update repository permissions
Conflicts Not Showing
Symptoms: Task failed but you can't find the conflict information.
Solution:
- Check your GitHub repository for the
cherry-kit/*branch - The branch contains the conflict markers
- Use Git locally to resolve:
git fetch origin
git checkout origin/cherry-kit/<pr>-<branch>
git status # Shows conflicted filesRepository Issues
Repository Not Appearing
Symptoms: You installed the GitHub App but repositories don't show.
Verify GitHub App Installation
- Go to GitHub → Settings → Applications
- Find "recommit.dev"
- Verify it has access to your repositories
Check Organization Permissions
If using an organization:
- Organization owners must approve the app
- Check pending installation requests
Refresh Repository List
- Go to Console → Repositories
- Click "Refresh" to sync with GitHub
- Wait a few seconds and check again
Repository Shows "Suspended"
Symptoms: Repository status shows "Suspended" in Console.
Cause: GitHub App access was suspended by an organization admin.
Solution:
- Go to GitHub organization settings
- Navigate to Installed GitHub Apps
- Find recommit.dev and unsuspend it
Repository Shows "Disconnected"
Symptoms: Repository shows disconnected status.
Causes:
- GitHub App was uninstalled
- Repository access was revoked
- Repository was transferred or deleted
Solution:
Check GitHub App Status
- Go to GitHub → Settings → Applications
- Verify recommit.dev is installed
- Verify it has repository access
Re-authorize if Needed
If the app was uninstalled:
- Re-install from Console → Settings
- Grant access to your repositories
- Refresh the Console repository list
Roadmap Issues
Roadmap Not Working
Symptoms: Roadmap is created but cherry-picks aren't using it.
Checklist:
- Roadmap is linked to a repository
- Branch names match exactly (case-sensitive)
- Branches exist in the repository
- Repository is enabled
Branches in Wrong Order
Symptoms: Cherry-picks happen but not to expected branches.
Explanation: Cherry-picks are processed in order v1 → v2 → v3 → main (reverse of the roadmap list). When a PR is merged, only branches after the source branch in processing order receive cherry-picks. For example, if roadmap is main v3 v2 v1 and a PR is merged to v2, only v3 and main will receive cherry-picks.
Solution:
- Go to Console → Roadmaps
- Edit your Roadmap
- Ensure branches are ordered from newest to oldest:
main v3 v2 v1
Missing Default Branch
Symptoms: Default branch is not receiving cherry-picks.
Solution:
- Edit your Roadmap
- Enable "Cherry-pick to Default Branch"
- Or add your default branch explicitly to the list
Authentication Issues
Login Failed
Symptoms: Can't log in with GitHub.
Clear Browser Data
- Clear cookies for recommit.dev
- Clear cookies for github.com
- Try logging in again
Check GitHub Status
- Visit GitHub Status (opens in a new tab)
- Verify OAuth services are operational
Try Incognito Mode
- Open an incognito/private window
- Attempt to log in
- If it works, browser extensions may be interfering
Permission Errors
Symptoms: "Permission denied" or "Unauthorized" errors.
Causes:
- OAuth token expired
- Organization permissions changed
- Repository access revoked
Solution:
- Log out of recommit
- Go to GitHub → Settings → Applications → Authorized OAuth Apps
- Revoke recommit.dev
- Log in again to re-authorize
Webhook Issues
Webhooks Not Received
Symptoms: Events happen in GitHub but recommit doesn't respond.
Webhooks are automatically configured when you install the GitHub App. Manual configuration is rarely needed.
Diagnostic Steps:
- Go to GitHub → Settings → Developer settings → GitHub Apps
- Find recommit.dev
- Check "Recent Deliveries" in Advanced tab
- Look for failed deliveries
If Deliveries Show Failures:
| Status Code | Meaning | Action |
|---|---|---|
| 200 | Success | Webhook received |
| 401 | Unauthorized | Re-install app |
| 500 | Server error | Retry or contact support |
| Timeout | Request timed out | Retry, usually temporary |
Performance Issues
Cherry-Picks Are Slow
Symptoms: Tasks stay in "Pending" status for a long time.
Possible Causes:
- High system load
- Large repositories
- Many concurrent tasks
Notes:
- Tasks are processed in order
- Large repos take longer
- Peak hours may have delays
Console Loading Slowly
Symptoms: Pages take a long time to load.
Solutions:
- Check your internet connection
- Try a different browser
- Clear browser cache
- Disable browser extensions
Getting More Help
Before Contacting Support
Prepare the following information:
- Organization name in recommit
- Repository name where issue occurs
- PR number (if applicable)
- Error messages (screenshots help)
- Steps to reproduce the issue
Contact Methods
- GitHub Issues: Report bugs or feature requests
- Email: support@recommit.dev
- Documentation: Check our guides first
Include Diagnostic Info
When reporting issues, include:
Organization: [your-org]
Repository: [repo-name]
PR Number: #XXX
Browser: Chrome/Firefox/Safari
Error Message: [exact text]
Steps:
1. I did X
2. Then Y
3. Got error ZQuick Reference
Common Error Codes
| Error | Meaning | Quick Fix |
|---|---|---|
repo_not_found | Repository doesn't exist | Check repo name |
branch_not_found | Target branch missing | Create branch |
permission_denied | Insufficient access | Re-authorize app |
merge_conflict | Conflicting changes | Resolve manually |
rate_limited | Too many API calls | Wait and retry |
Status Meanings
| Status | Meaning |
|---|---|
| ✅ Success | Everything worked |
| ⏳ Pending | In queue |
| 🔄 Processing | Currently running |
| ❌ Failed | Error occurred |
| ⚠️ Warning | Partial success |