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.

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 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.