usestrix/strix · error · ValueError

Unable to resolve a base ref for diff-scope. Pass --diff-bas

Error message

Unable to resolve a base ref for diff-scope. Pass --diff-base explicitly (for example: --diff-base origin/main).

What it means

Raised by _resolve_base_ref (utils.py:724) when diff-scope mode needs a comparison base but none can be resolved: the caller did not pass --diff-base, no GitHub base SHA was derivable, the origin HEAD ref is missing, and neither refs/remotes/origin/main nor refs/remotes/origin/master exists in the repository. Strix refuses to guess a base silently, so it demands an explicit one.

Source

Thrown at strix/interface/utils.py:724

        github_candidate = f"refs/remotes/origin/{github_base_ref}"
        if _git_ref_exists(repo_path, github_candidate):
            return github_candidate

    github_base_sha = _extract_github_base_sha(env)
    if github_base_sha and _git_ref_exists(repo_path, github_base_sha):
        return github_base_sha

    origin_head = _resolve_origin_head_ref(repo_path)
    if origin_head and _git_ref_exists(repo_path, origin_head):
        return origin_head

    if _git_ref_exists(repo_path, "refs/remotes/origin/main"):
        return "refs/remotes/origin/main"

    if _git_ref_exists(repo_path, "refs/remotes/origin/master"):
        return "refs/remotes/origin/master"

    raise ValueError(
        "Unable to resolve a base ref for diff-scope. Pass --diff-base explicitly "
        "(for example: --diff-base origin/main)."
    )


def _get_current_branch_name(repo_path: Path) -> str | None:
    result = _run_git_command(repo_path, ["rev-parse", "--abbrev-ref", "HEAD"], check=False)
    if result.returncode != 0:
        return None
    branch_name = result.stdout.strip()
    if not branch_name or branch_name == "HEAD":
        return None
    return branch_name


def _parse_name_status_z(raw_output: bytes) -> list[DiffEntry]:
    if not raw_output:
        return []

View on GitHub (pinned to 8551339130)

Solutions

  1. Pass --diff-base explicitly, e.g. --diff-base origin/develop
  2. Fetch the base branch first: git fetch origin develop, then use --diff-base origin/develop
  3. In CI, configure the checkout to fetch the default branch (fetch-depth: 0 or refs spec)
  4. Rename/align to main or master, or create refs/remotes/origin/main by fetching the default branch

Example fix

# before
strix -t . --diff-scope  # default branch is 'develop'
# ValueError: Unable to resolve a base ref ...

# after
git fetch origin develop
strix -t . --diff-scope --diff-base origin/develop
Defensive patterns

Strategy: validation

Validate before calling

if not diff_base:
    if not (_git_ref_exists(repo, "refs/remotes/origin/main") or _git_ref_exists(repo, "refs/remotes/origin/master")):
        raise SystemExit("default branch is not main/master; pass --diff-base origin/<branch>")

Type guard

def has_resolvable_base(repo_path) -> bool:
    return any(_git_ref_exists(repo_path, r) for r in ("refs/remotes/origin/main", "refs/remotes/origin/master"))

Try / catch

try:
    run_diff_scope_scan()
except ValueError as e:
    if "Unable to resolve a base ref" in str(e):
        fetch_and_retry_with_explicit_base()  # git fetch origin <default>; --diff-base origin/<default>
    else:
        raise

Prevention

When it happens

Trigger: Enabling diff-scope on a repo whose default branch is neither main nor master (e.g. 'develop', 'trunk') with no --diff-base given; a shallow/partial clone lacking remote refs; a repo with no 'origin' remote; CI checkouts that fetch only the PR ref without base branch refs.

Common situations: GitHub Actions default checkout (fetch-depth 1, no other branches); GitLab 'trunk'-default projects; forks where origin points at the fork with unrelated branches; repos using non-standard default branch names.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/c07d0a24c2bed1d6. Report an issue: GitHub.