Problem
CircleCI’s default for the built-in checkout step is a blobless clone (faster checkout for most projects). Some jobs need more of the repository (history and stored file objects) than that mode fetches. Those jobs may start failing in CircleCI even when a full clone of the same repository works elsewhere.
CircleCI’s changelog and documentation describe this rollout and when to opt into blobless or full explicitly. This article only covers choosing full in config. It does not cover SSH auth, submodules, or replacing the built-in checkout with your own clone commands (those are separate topics).
Issues that might point here:
A
runstep or job logic that reads commit history or older versions of files, not only the tree for the current commit.Shell commands that inspect history, attribute lines to authors, or compare revisions, when those commands need objects a blobless checkout has not fetched yet.
Any step that assumes a full clone of the repository (complete local object store) even though the job uses CircleCI’s
checkoutstep.
Example log patterns below are illustrative only. They are not copied from a single reproduced failure. Wording depends on the command that failed.
fatal: missing blob object ... error: Could not read ... Failed to blame ... Unable to read file at revision ...
Cause
Per the configuration reference, a blobless clone reduces what is fetched from the remote by filtering out objects not tied to the current commit. If a later step needs historical file contents or other objects that were not fetched, it can fail. The same page states that in those cases you can use checkout with method: full.
Background on the default checkout change: Introducing a faster checkout option and related changelog (maintenance) entries.
Solution
For jobs that need a full clone, set method: full on checkout (per docs).
Open
.circleci/config.ymlfor the project.Find the job that needs a complete checkout (often the one that failed).
Use an explicit
fullcheckout:
jobs:
build:
docker:
- image: cimg/base:current
steps:
- checkout:
method: full
- run:
name: Your step
command: # your command hereTo keep blobless explicit in the file (same behavior as the platform default when default is blobless), use:
steps:
- checkout:
method: bloblessSubmodules: per the documentation, the built-in checkout step does not initialize submodules. Use additional run steps if you need them; see the checkout documentation.
Verification
Commit and push the config change.
Rerun the pipeline on a branch that builds.
Confirm the
checkoutstep succeeds and the step that used to fail either passes or shows a different, more specific error.If it still fails, the cause may be submodules, a custom clone, or VCS permissions, not blobless vs full.
Optional debugging: after checkout, add a temporary run step that prints whether the remote uses a partial-clone filter (for example blob:none) or a promisor remote. Under blobless those settings are usually present; under full they are often empty. Use the commands your version-control tooling documents for reading remote.origin.partialclonefilter and related promisor settings. Remove the step after debugging.
Example logs
Synthetic example only (not from one captured failure):
[step: run cmd] ... ERROR: ... revision ... not found in repository ... read-object: could not get object info
Adding checkout: method: full may resolve failures that are truly caused by missing repository objects after a blobless checkout. It is not guaranteed for every error in the logs above; submodule and auth problems need different fixes.