Common Errors and How to Fix Them

Introduction

Every tool has its error messages. DevLoop Runner is no exception.

When you first set up, change a configuration, or connect a new repository, things can go wrong. The good news is that most errors follow predictable patterns, and once you know the cause, fixing them is quick.

This article catalogs the most common errors you'll encounter while using DevLoop Runner, explains why they happen, and walks through the steps to resolve each one. Bookmark this page as a troubleshooting reference.

Authentication Errors

Authentication errors are the most frequent category. They occur when the credentials DevLoop Runner needs to communicate with GitHub or AI services are misconfigured.

Incorrect API Key

Symptoms:

• "Invalid API key" or "Authentication failed" error message
• Dev Run fails immediately upon starting

Cause:

• API key is not configured correctly
• Typo in the API key
• Wrong environment variable name

How to fix:

1. Check that the API key is correctly entered in the settings
2. Look for leading or trailing whitespace in the key
3. Re-enter the key using copy-paste
4. Verify the key is active in your API provider's dashboard

Expired API Key

Symptoms:

• Authentication worked before but suddenly started failing
• "API key expired" or "Token expired" message

Cause:

• The API key's validity period has lapsed
• The key was revoked by the service provider

How to fix:

1. Log in to your API provider's dashboard
2. Check the key's expiration date
3. If expired, generate a new key
4. Update the key in DevLoop Runner's settings

Insufficient GitHub Token Permissions

Symptoms:

• Repository list doesn't load
• "Resource not accessible by integration" error

Cause:

• The GitHub access token lacks required scopes

How to fix:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Find the token used by DevLoop Runner
3. Confirm these scopes are granted:
   • repo (full repository access)
   • workflow (GitHub Actions execution, if needed)
4. If scopes are missing, regenerate the token with correct permissions

Repository Connection Errors

Errors related to connecting with repositories.

Private Repository Access

Symptoms:

• Public repositories appear but private ones don't
• "Repository not found" error

Cause:

• Access token lacks private repository permissions
• Organization repositories may require SSO authorization

How to fix:

1. Confirm the access token includes the repo scope
2. For Organization repositories:
   • Go to GitHub Settings → Personal access tokens and select the token
   • Use "Configure SSO" to authorize the Organization
3. If using a GitHub App integration, ask the Organization admin to approve the installation

Branch Protection Rules

Symptoms:

• PR creation or push fails with "Permission denied"
• Errors referencing "Branch protection rule"

Cause:

• Branch protection rules are configured on the default branch (main/master)
• Direct pushes are blocked

How to fix:

DevLoop Runner works by creating branches and opening PRs, which is generally compatible with branch protection. If errors persist:

1. Check the repository settings → Branches → Branch protection rules
2. Verify that DevLoop Runner's bot account is listed as an allowed actor
3. If needed, add the bot account to "Restrict who can push to matching branches"

Dev Run Execution Errors

Errors that occur during Dev Run processing.

Insufficient Issue Content

Symptoms:

• Dev Run stalls at the planning phase
• The generated plan is too vague to proceed to implementation

Cause:

• Issue description lacks enough detail for AI to determine an implementation approach
• Requirements are ambiguous, preventing test scenario design

How to fix:

1. Review the Issue description. Confirm it includes:
   • What to implement (specific feature description)
   • How to implement it (technical approach)
   • Acceptance criteria (what defines "done")
2. Rewrite the Issue following effective Issue writing practices
3. Re-run the Dev Run

Phase Failure

Symptoms:

• A specific phase (design, implementation, testing, etc.) errors out
• "Phase failed" message appears

Cause:

• AI couldn't interpret the codebase's unique structure
• Dependency issues prevent a successful build
• Test framework configuration problems

How to fix:

1. Read the error message to identify the failure cause
2. Use the rollback feature to return to the failed phase
3. Add more context to the Issue (file paths, libraries used, constraints)
4. Alternatively, use phase skip to bypass the problematic phase and handle it manually later
5. Re-run the Dev Run

Run Stalled or Hanging

Symptoms:

• Dev Run stops making progress
• A phase shows "processing" for an extended period

Cause:

• Issue scope is too large
• AI is working through complex logic generation
• Network connectivity issues

How to fix:

1. If no progress after waiting, cancel the job
2. Split the Issue into smaller, more focused Issues
3. Try changing the execution mode to "implementation only" to skip the planning phase
4. Check your network connection

Handling Test Failures

When tests generated by Dev Run don't pass.

Generated Tests Conflict with Existing Code

Symptoms:

• Newly generated tests fail
• Existing tests pass, but new ones don't

Cause:

• AI didn't fully understand the existing codebase's behavior
• Test expectations don't match actual behavior

How to fix:

1. Examine the failing test content
2. Determine whether the test expectation is wrong or the implementation is wrong
3. If the test is wrong: request a fix via PR review comment
4. If the implementation is wrong: roll back and re-run

Existing Tests Break

Symptoms:

• Existing tests fail after a Dev Run
• CI reports failures in the pre-existing test suite

Cause:

• AI's changes affected existing functionality
• API changes invalidated existing test assumptions

How to fix:

1. Identify which tests are failing
2. Determine whether the failure is from an intentional change or a bug
3. Intentional change: request test updates via review comment
4. Bug: revise the PR, or don't merge and re-run with an improved Issue description

Environment Differences

Symptoms:

• Tests pass during Dev Run but fail in CI
• Tests pass locally but not in CI

Cause:

• Node.js version differences
• Environment variable discrepancies
• OS or filesystem differences (e.g., path separators)

How to fix:

1. Check CI logs for specific error messages
2. Compare CI and Dev Run environments (Node.js version, OS, etc.)
3. Adjust CI configuration as needed
4. For environment-dependent tests, use conditional logic or mocks

Finalize Errors

Errors when converting a Draft PR to a public PR.

Merge Conflicts

Symptoms:

• "Merge conflict" error during Finalize
• PR shows "This branch has conflicts"

Cause:

• Other changes were merged to the base branch (main) after the Draft PR was created, causing conflicts

How to fix:

1. Review the conflict details
2. For minor conflicts: resolve using GitHub's web UI or manually
3. For major conflicts: re-run the Issue through Dev Run against the latest main branch

CI Checks Not Passing

Symptoms:

• Finalize succeeds but merge is blocked
• "Required status checks have not passed" message

Cause:

• Branch protection requires CI checks to pass before merging
• CI checks failed or weren't triggered

How to fix:

1. Check the PR's Checks tab for CI status
2. If checks failed, review the logs and address the issues
3. If checks weren't triggered, push a new commit to the branch to re-trigger CI

Rate Limiting

Errors from hitting API rate limits.

AI API Rate Limits

Symptoms:

• "Rate limit exceeded" error
• Errors during parallel Dev Run execution

Cause:

• API call count reached the plan's limit
• Too many requests sent in a short period

How to fix:

1. Wait and retry (limits typically reset within minutes to an hour)
2. Reduce the number of parallel Dev Runs
3. Consider upgrading your API plan if limits are consistently hit

GitHub API Rate Limits

Symptoms:

• GitHub operations (PR creation, comment posting) fail
• "API rate limit exceeded" error

Cause:

• Hit GitHub's API rate limit (5,000 requests per hour for authenticated users)

How to fix:

1. Wait and retry
2. Reduce parallel processing concurrency
3. If using a GitHub App, check the per-installation rate limit

Troubleshooting Flowchart

A general approach when you encounter any error.

Loading diagram...

Summary

• Authentication errors are usually resolved by verifying and re-issuing API keys
• Repository connection errors require checking token permissions and repository settings
• Dev Run execution errors call for richer Issue descriptions or smaller scope
• Test failures need root cause analysis from both the test and implementation sides
• Finalize errors are addressed by resolving conflicts or regenerating the PR
• Rate limits are handled by waiting or reducing parallel execution count
• Always read the error message carefully and identify the cause before attempting a fix

Errors are part of development. The key is staying calm, identifying the root cause, and applying the right fix. Use this article as a reference to minimize your troubleshooting time and get back to building.