---
title: GitHub Sync Failures
description: "## A collection shows as \"Unhealthy\" A collection is marked unhealthy after 3 or more consecutive failed syncs, including syncs where the manifest is invalid. The daily background check skips unhealthy collections, so they stay unhealthy until you retry them.…"
url: "https://brightleafdigital.io/docs/github-sync-failures/"
updated: "2026-10-20"
category: GravityOps Code Snippet Manager / Troubleshooting
---

# GitHub Sync Failures

## A collection shows as "Unhealthy"

A collection is marked unhealthy after 3 or more consecutive failed syncs, including syncs where the manifest is invalid. The daily background check skips unhealthy collections, so they stay unhealthy until you retry them. Check the **Sync Log** tab for the error message from the most recent attempt.

## 404 — Manifest not found

**Cause:** The `snippets.json` file does not exist at the expected path, or the branch/subdirectory in the URL is wrong.

**Fix:**

- Verify the URL in the collection's row matches where `snippets.json` lives in the repository.
- Check the branch name. When no branch is given, GOCSM tries `main` and then `master`. To use a different branch, click **Edit** on the collection and set **Branch**, or include the branch in the URL.
- If you specified a subdirectory, confirm `snippets.json` is inside that subdirectory, not at the repo root.
- If the repository is private, define `GOCSM_GITHUB_TOKEN` in `wp-config.php` (GitHub answers 404 rather than 403 for private repositories you cannot see). If the token is already defined, check that it has read access to this repository's contents. See [Private repositories](../03-github-collections/02-adding-a-collection.md#private-repositories).

## 401 / 403 — Token rejected

**Cause:** `GOCSM_GITHUB_TOKEN` is defined but expired, revoked, lacks access to the repository, or has hit GitHub's API rate limit.

**Fix:** Generate a new token with read-only Contents access to the repository, update the constant, and click **Retry Sync**.

## Hash mismatch

**Cause:** The file contents do not match the SHA-256 hash declared in `snippets.json`. This can happen if the file was edited after the manifest was last updated.

**Fix:** If you maintain the library, regenerate the hash for the changed file and update `snippets.json`. If you are a consumer, contact the library author.

## GitHub rate limits and transient HTTP failures

Without a token, GOCSM fetches raw GitHub URLs, which are not subject to the GitHub API rate limit. With `GOCSM_GITHUB_TOKEN` defined, it uses the GitHub Contents API, which allows 5,000 requests per hour per token. Either way it uses `If-None-Match` / ETag caching for manifests to avoid unnecessary downloads, but many collections or repeated manual syncs can still trigger GitHub or host-level throttling.

**Fix:** Spread manual syncs out over time, then retry later.

## Invalid manifest

**Cause:** `snippets.json` does not conform to the expected schema (missing required fields, wrong types, etc.).

**Fix:** Check the **Sync Log** for a `manifest_invalid` event with details about which field failed. See [Creating Your Own Snippet Library](../03-github-collections/04-creating-your-own-snippet-library.md) for the correct manifest format.

## Resetting an unhealthy collection

After fixing the underlying issue, click **Retry Sync** on the collection in the **Collections** tab. A successful sync clears the unhealthy state.