[validation_error] Failed to verify existence of branch 'main' in repository foo/bar/repo.git. Please ensure the branch name is correct

Support Bug Reports
, ,
1

Where does the bug appear (feature/product)?

Cursor SDK

Describe the Bug

Intermittent validation_error verifying main branch when creating self-hosted agents, despite startingRef: "main"

We are seeing intermittent failures when starting Cursor self-hosted cloud agents through the Cursor SDK.

Error:

[validation_error] Failed to verify existence of branch 'main' in repository foo/bar/repo.git. Please ensure the branch name is correct.

Context:

  • SDK: @cursor/sdk 1.0.19
  • Runtime: self-hosted worker pools
  • We explicitly pass startingRef: "main" in Agent.create
  • The branch exists and most agent creations with the same repo/ref succeed
  • The failure is intermittent with unchanged inputs

Create config shape:

cloud: {
  repos: [{ url: "foo/bar/repo.git", startingRef: "main" }],
  env: { type: "pool", name: "john-doe" }
}

Observed behavior:

  • Some agent starts fail before a durable run is recorded on our side.
  • GitLab integration is set. Repositories synced
  • Retrying the exact same create request often succeeds later.
  • We added application-level retries for this exact error, but the issue still reappears.
  • In prior incidents, a similar startup validation error sometimes appeared to create a cloud agent/run anyway, which made blind retries risky because duplicate agents could work on the same task.

Expected behavior:

  • If startingRef: "main" is provided and the branch exists, Agent.create should not intermittently fail branch verification.
  • If Cursor creates an agent/run but the SDK returns an error, the response/error should include enough stable identifiers to recover/adopt that run without creating duplicates.

Question:

Can Cursor investigate why branch verification for an existing explicit startingRef intermittently returns validation_error, and whether the SDK/API can return the created agent/run IDs when the backend has already created work despite surfacing this startup error?

Steps to Reproduce

  1. Configure a Cursor self-hosted worker pool.

  2. Use a repository whose default branch is main.

  3. Start cloud agents repeatedly against that pool with an explicit repo startingRef of main.

  4. Keep the request inputs stable: same repository, same startingRef, same pool, same model family.

  5. Observe that most starts succeed, but some intermittently fail during startup with:

    [validation_error] Failed to verify existence of branch ‘main’ in repository …

  6. Retry the same request later and observe that it can succeed without any repository or branch change.

Expected Behavior

When startingRef: "main" is provided and the branch exists:

  • Agent startup should consistently accept the explicit ref.
  • Cursor should not intermittently fail branch verification for unchanged inputs.
  • Cursor should not need to resolve the repository default branch before honoring the explicit startingRef.

If the backend creates a cloud agent or run but the SDK/API returns an error:

  • The error should include stable identifiers for the created agent/run.
  • The caller should be able to recover/adopt the in-flight work.
  • Retrying the same task should not risk creating duplicate agents that perform the same work.

Operating System

Linux

Version Information

  • SDK: @cursor/sdk 1.0.19
  • GitLab

For AI issues: which model did you use?

composer: 2.5

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

5

Hi @Artur_Artsabliuk,

Thanks for flagging this!

The issue stems from some recent rate limiting we’ve been encountering in our integration with GitLab. The team is actively working on a resolution.

Once we’re out of the woods, we should explore ways to improve resiliency here, as you’ve suggested!