infiniflow/ragflow · error · InsufficientPermissionsError

Your GitHub token does not have sufficient permissions for t

Error message

Your GitHub token does not have sufficient permissions for this repository (HTTP 403).

What it means

InsufficientPermissionsError raised when the validation probe gets HTTP 403 without the SSO message. The token authenticates but lacks the required repository scope — the credential is valid, its grants are not. Separating 403 from 401 lets the system suggest scope fixes instead of token rotation.

Source

Thrown at common/data_source/github/connector.py:744

                        raise ConnectorValidationError(
                            f"Your GitHub token is missing authorization to access the `{self.repo_owner}` organization. Please follow the guide to authorize your token: {SSO_GUIDE_LINK}"
                        )
                    # If not an org, try as a user
                    user = self.github_client.get_user(self.repo_owner)

                    # Check if we can access any repos
                    total_count = user.get_repos().totalCount
                    if total_count == 0:
                        raise ConnectorValidationError(f"Found no repos for user: {self.repo_owner}. Does the credential have the right scopes?")

        except RateLimitExceededException:
            raise UnexpectedValidationError("Validation failed due to GitHub rate-limits being exceeded. Please try again later.")

        except GithubException as e:
            if e.status == 401:
                raise CredentialExpiredError("GitHub credential appears to be invalid or expired (HTTP 401).")
            elif e.status == 403:
                raise InsufficientPermissionsError("Your GitHub token does not have sufficient permissions for this repository (HTTP 403).")
            elif e.status == 404:
                if self.repositories:
                    if "," in self.repositories:
                        raise ConnectorValidationError(f"None of the specified GitHub repositories could be found for owner: {self.repo_owner}")
                    else:
                        raise ConnectorValidationError(f"GitHub repository not found with name: {self.repo_owner}/{self.repositories}")
                else:
                    raise ConnectorValidationError(f"GitHub user or organization not found: {self.repo_owner}")
            else:
                raise ConnectorValidationError(f"Unexpected GitHub error (status={e.status}): {e.data}")

        except Exception as exc:
            raise Exception(f"Unexpected error during GitHub settings validation: {exc}")

    def validate_checkpoint_json(self, checkpoint_json: str) -> GithubConnectorCheckpoint:
        return GithubConnectorCheckpoint.model_validate_json(checkpoint_json)

    def retrieve_slim_document(

View on GitHub (pinned to 554fb1133a)

Solutions

1. Recreate the PAT including the 'repo' scope (classic) or add the specific repositories + 'Contents: Read' permission (fine-grained).
2. For GitHub Apps, have an org admin grant the app access to the needed repositories.
3. If SSO was the real cause, authorize the token for the org (see the SSO-specific error path).

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError:
    show_scope_instructions('add repo scope / grant repo access to the token')

When it happens

Trigger: A token with only public/read:public scope calling get_repo/get_contents on a private repo, or an org-restricted fine-grained PAT probing a repo outside its allowlist, returns 403.

Common situations: Classic PAT created with just 'public_repo'; fine-grained PAT whose repository access list omits the target; org-app installation missing 'Contents: read' on some repos.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• Found no repos for organization: {self.repo_owner}. Does the
• Found no repos for user: {self.repo_owner}. Does the credent
• main() must return a value. Use null for an empty result.
• message.compileNotSupported
• Failed to fetch memory list

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/7f74a8f24cae60b0. Report an issue: GitHub.