pockethub/PocketHub · error · IOException

Request for Git Reference was unsuccessful

Error message

Request for Git Reference was unsuccessful

What it means

getValidRef() throws this IOException when the HTTP request for the GitReference completes but is not successful (non-2xx). The wrapped Single signals an error to the subscriber of refresh(). It distinguishes API-level failure from a valid-but-invalid ref payload.

Solutions

1. Check the ref name spelling and that the branch/tag exists ('git ls-remote origin').
2. Verify authentication/token scopes for the repository (401/403).
3. Add retry logic (RxJava retryWhen with backoff) for transient 5xx/network errors.
4. Handle the IOException in the subscribe error consumer and surface a user-facing message.

Example fix

// before
store.refreshGist(...)
    .subscribe(this::onLoaded);
// after
store.refreshGist(...)
    .retryWhen(errors -> errors.flatMap(e -> Observable.timer(1, TimeUnit.SECONDS)))
    .subscribe(this::onLoaded, err -> showError(err.getMessage()));

// check ref exists and token valid:
// git ls-remote https://github.com/<owner>/<repo>.git refs/heads/<ref>

source.subscribe(
    { ref -> /* handle */ },
    { e -> showError(if (e is IOException) e.message else "unknown") }
)

When it happens

Trigger: The GET refs/{ref} call returns a non-successful HTTP code — 404 (branch/tag doesn't exist), 401/403 (auth problems), 422, or 5xx from GitHub.

Common situations: Requesting a branch that was deleted or never existed; expired/insufficient auth token; private repo accessed without permission; transient GitHub 5xx.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Reference does not have associated commit SHA-1
• Unexpected response code:

AI-assisted analysis of pockethub/PocketHub@8228cb8f71 (2026-09-11). Data as JSON: /api/errors/d7bbc97baa4da6da. Report an issue: GitHub.

Appendix: source

Thrown at app/src/main/java/com/github/pockethub/android/core/code/RefreshTreeTask.java:83

    private boolean isValidRef(GitReference ref) {
        return ref != null && ref.object() != null
                && !TextUtils.isEmpty(ref.object().sha());
    }

    private Single<GitReference> getValidRef(GitService service, GitReference ref, String branch) {
        if (!isValidRef(ref)) {
            return service.getGitReference(repo.owner().login(), repo.name(), branch)
                    .map(response -> {
                        if (response.isSuccessful()) {
                            GitReference fetchedRef = response.body();
                            if (isValidRef(fetchedRef)) {
                                return fetchedRef;
                            } else {
                                throw new IOException("Reference does not have associated commit SHA-1");
                            }
                        } else {
                            throw new IOException("Request for Git Reference was unsuccessful");
                        }
                    });
        }

        return Single.just(ref);
    }

    private Single<String> getBranch(GitReference ref) {
        String branch = RefUtils.getPath(ref);
        if (branch == null) {
            branch = repo.defaultBranch();
            if (TextUtils.isEmpty(branch)) {
                return ServiceGenerator
                        .createService(context, RepositoryService.class)
                        .getRepository(repo.owner().login(), repo.name())
                        .map(response -> response.body().defaultBranch());
            }
        }

View on GitHub (pinned to 8228cb8f71)