Troubleshooting RepoBird Issues

Troubleshooting RepoBird Issues

While RepoBird aims for seamless operation, you might occasionally encounter issues. This guide covers the most common problems and their solutions.

Why might the agent fail to create a pull request or push changes?

While RepoBird aims for seamless operation, failures can occasionally occur. Here are the most common reasons and how to resolve them:

Permission Issues

Problem: The GitHub App might lack the necessary permissions for certain actions.

Common Example: By default, RepoBird does not have permission to write to sensitive paths like .github/workflows/. Attempting to create or modify workflow files will cause the push to fail.

Solution:

• Review the GitHub App permissions for your repositories
• Ensure the App has appropriate permissions for the repositories and actions you require
• Be mindful of security implications when granting additional permissions
• Consider whether workflow modifications should be handled manually for security reasons

Authentication Problems

Problem: Temporary issues with GitHub authentication or token validity can prevent interaction.

Solution:

• Check if the GitHub App installation is still active
• Try re-installing the RepoBird GitHub App if authentication issues persist
• Verify that your repository hasn't been transferred or had ownership changes
• Contact support if authentication problems continue

Complex Code Conflicts

Problem: Significant conflicts between the agent's changes and the current state of the branch might prevent automatic merging or pushing.

Solution:

• Ensure your target branch is up to date before triggering RepoBird
• Consider breaking large changes into smaller, more manageable tasks
• Review any recent changes to the target branch that might conflict
• Use the plan command first to identify potential conflict areas

Repository Configuration

Problem: Branch protection rules or other repository settings might block the agent's push attempts.

Solution:

• Review branch protection rules for your target branch
• Temporarily adjust protection rules if necessary (and safe to do so)
• Ensure RepoBird has the necessary permissions to bypass protection rules if configured
• Consider using a different target branch that doesn't have strict protection rules

General Troubleshooting Steps

If failures persist, try these steps:

1. Check the GitHub App permissions and repository settings
2. Simplify the task by breaking it into smaller components
3. Use the plan command to review the approach before implementation
4. Contact support with specific error details and repository information

How to use the Plan Command for better results

The plan command is a powerful feature that helps ensure RepoBird understands your requirements before implementation. Here's how to use it effectively:

Start with Planning

Comment @repobirdbot plan on any GitHub issue to get an AI-generated implementation plan.

Benefits:

• Better understanding of requirements
• Higher success rates
• Opportunity to review and adjust before implementation
• Reduced chance of conflicts and errors

Works on Issues

Unlike basic/pro commands, the plan command can be triggered directly on GitHub issues (not just pull requests). This makes it perfect for:

• New feature requests
• Bug reports
• Refactoring tasks
• Complex implementation scenarios

Review Before Implementation

RepoBird will analyze your issue, research your codebase, and post a detailed plan as a comment for your review. The plan typically includes:

• Problem Analysis: How RepoBird understands the issue
• Proposed Approach: The strategy for solving the problem
• Implementation Steps: Detailed breakdown of what will be done
• Files to be Modified: List of files that will be changed
• Potential Challenges: Areas that might need special attention

Execute the Plan

After reviewing the plan, quote reply to the plan comment with:

• @repobirdbot basic for standard implementation
• @repobirdbot pro for complex implementation with advanced AI models

This approach leads to higher success rates and better alignment with your expectations. For detailed examples and best practices, check out our Plan Command Guide.

Performance Optimization Tips

Writing Better Issue Descriptions

Be Specific: Include relevant file paths, function names, and code snippets in your issue description.

Provide Context: Explain why you need the change and any constraints or requirements.

Include Examples: Show what the current behavior is and what you want it to become.

Using Effective Commands

Use Plan First: For complex tasks, always start with the plan command to ensure proper understanding.

Be Explicit: Instead of @RepobirdBot basic fix this, try @RepobirdBot basic Fix the login validation to handle empty email addresses properly.

Specify Requirements: Include testing requirements, style preferences, and any dependencies.

Optimizing Repository Structure

Clear Documentation: Keep your README and documentation up to date so RepoBird can understand your project structure.

Consistent Patterns: Use consistent coding patterns and naming conventions that RepoBird can learn from.

Good Test Coverage: Well-tested code helps RepoBird understand expected behavior.

Common Error Messages and Solutions

"Permission denied" errors

Cause: Insufficient GitHub App permissions Solution: Review and update GitHub App permissions for your repository

"Branch not found" errors

Cause: Specified source or target branch doesn't exist Solution: Verify branch names and ensure they exist in your repository

"Timeout" errors

Cause: Task exceeded the 45-minute execution limit Solution: Break the task into smaller components or simplify the requirements

"Conflict" errors

Cause: Changes conflict with recent updates to the target branch Solution: Update your branch and retry, or resolve conflicts manually

Getting Additional Help

If you're still experiencing issues after trying these troubleshooting steps:

1. Check our other guides for specific feature documentation
2. Review recent blog posts for updates and known issues
3. Contact our support team with:
   • Repository name and URL
   • Specific error messages
   • Steps to reproduce the problem
   • Screenshots if applicable

Our support team is ready to help you get the most out of RepoBird!

Best Practices Summary

• Always start with the plan command for complex tasks
• Provide detailed issue descriptions with context and examples
• Keep your repository documentation up to date
• Use appropriate branch permissions and protection rules
• Break large tasks into smaller, manageable components
• Test RepoBird on simple tasks first to understand its capabilities

Following these practices will help you avoid common issues and get better results from RepoBird's AI-powered automation.