Errors and how to fix them

Your Personal Access Token is invalid, expired, or does not have the right permissions.

Fix: Go to GitHub → Settings → Developer Settings → Fine-grained tokens. Check if the token is expired. If so, generate a new one with Contents: Read and write permission on the correct repository. Paste the new token into the plugin settings.

Also verify that the token begins with ghp_ or github_pat_. The plugin will reject tokens that do not match this format.

The plugin validates the token format before making any API call. If you see this message, the token in your settings does not start with ghp_ or github_pat_.

Fix: Check that you copied the full token without any leading or trailing spaces. Legacy "classic" tokens start with ghp_. Fine-grained tokens start with github_pat_. If neither, regenerate the token.

The plugin cannot find the repository. This usually means the username, repository name, or branch is entered incorrectly — or the token does not have access to that repository.

Fix: Double-check all three fields: username (your GitHub handle, not email), repository name (exactly as it appears on GitHub, case-sensitive), and branch (default is main). Also ensure your token has access to the specific repository — fine-grained tokens are scoped per-repo.

GitHub has temporarily throttled your requests. The plugin automatically retries with a backoff delay when this happens. You may see the status bar show "syncing" for a longer period than usual.

If it keeps failing: Reduce the Concurrency setting in plugin preferences (from 5 down to 2 or 1). This slows down uploads but makes them less likely to trigger rate limits. Very large vaults (1000+ files) may need this adjustment.

Large vaults with hundreds or thousands of files may take several minutes on the first push. Subsequent pushes are faster because only changed files are uploaded.

Tips:

• Use the Ignored Paths setting to exclude large attachment folders you do not need synced
• Individual files over 50 MB cannot be synced via the GitHub API and will be skipped
• Keep the vault open and Obsidian in the foreground during the first sync — some mobile OSes suspend background processes

Currently, there is no automatic conflict merging. When you Pull, the remote (GitHub) version of a file replaces the local version if they differ. Any local changes that were not pushed first will be overwritten.

Best practice: Always push before switching devices and pull immediately after switching. If you suspect a conflict, check GitHub's commit history to find the version you need before pulling.

Pull brings your local vault in sync with the remote. If a file exists locally but not on GitHub, it may be deleted during pull if it was not on the remote. This can happen if you forgot to push after creating the file.

Recovery: GitHub keeps full commit history. Go to your repository on GitHub, click Commits, find a commit before the deletion, and restore the file from there.

This is also why maintaining a local backup of your vault is recommended, separate from the GitHub sync.

You have two or more files that differ only in capitalisation (e.g., Notes.md and notes.md). On macOS and Windows (which have case-insensitive filesystems), these are treated as the same file and one will silently overwrite the other.

Fix: Rename one of the files in Obsidian to remove the ambiguity before syncing. The plugin will flag the specific filenames so you know which ones to address.

You triggered a second Push or Pull while one is still running. The plugin only allows one sync operation at a time.

Fix: Wait for the current operation to complete (watch the status bar at the bottom of Obsidian). Then trigger the command again if needed.

Files can be skipped for the following reasons:

• The file matches an entry in Ignored Paths
• The file is inside .obsidian/ and Ignore .obsidian folder is enabled
• The file exceeds the 50 MB size limit imposed by the GitHub API
• The file path contains characters that are invalid in GitHub repository paths

Check your ignored paths configuration and file sizes if the skip is unexpected.