If a PDF opens perfectly on GitLab but shows “file damaged or unsupported” on your Mac, chances are you are staring at a Git LFS pointer, not the real file. This article walks through the problem, why it happens, how to debug it, and when Git LFS should or should not be used.
The Story: “It Works on GitLab, Why Not on My Mac?”
I had a repository that stored personal and career documents: offer letters, appointment letters, PDFs, certificates. Everything looked fine on GitLab.
I could click a PDF in the GitLab UI and it opened perfectly.
But locally on macOS, Preview threw this error:
“The file could not be opened. It may be damaged or use a file format Preview doesn’t recognize.”
At first glance, this looked like:
- A macOS issue
- A corrupted PDF
- A bad download
None of those were true.
First Clue: The File Size Looked Wrong
In GitLab, I noticed something odd:
- File size: 132 bytes
- Label: LFS
A real PDF is never 132 bytes.
That was the first red flag.
Second Clue: The file Command Never Lies
On macOS, I ran:
file "File1.pdf"
Output:
ASCII text
A real PDF should say:
PDF document
At this point, the mystery was solved.
The Real Problem: Git LFS Pointer Files
What I had locally was not a PDF.
It was a Git LFS pointer file, which looks something like this internally:
version https://git-lfs.github.com/spec/v1
oid sha256:xxxxxxxx
size 245678
This is just metadata that tells Git where the real file lives.
Why GitLab Worked
GitLab automatically fetches LFS objects from storage and renders them in the UI.
Why macOS Failed
- My local repository:
- Did not have Git LFS properly initialized
- Never downloaded the actual binary
- Only checked out pointer files
macOS Preview tried to open a text file as a PDF and failed.
Why This Happens So Often
Git LFS adds invisible complexity.
Everything works fine until:
- You clone the repo on a new machine
- Git LFS is not installed
- Or LFS is installed but not initialized per repo
At that point:
- Files look normal
- Names end with
.pdf - But content is not real
The Deeper Question: Should These Files Be in Git LFS at All?
This repo contained:
- PDFs
- Offer letters
- Certificates
- Personal documents
These files are:
- Small
- Rarely change
- Meant to be opened offline
- Often shared with non-developers
Using Git LFS here was technically valid, but practically wrong.
Solution Path 1: Fix Git LFS (Short-Term)
If you want to keep LFS:
git lfs install
git lfs pull
This downloads real binaries and replaces pointers.
But this still leaves long-term issues:
- Tooling dependency
- Offline failures
- Confusion for future clones
Solution Path 2: Remove PDFs from Git LFS Permanently (Best Choice)
For document repositories, this is the right fix.
Step 1: Stop tracking PDFs with LFS
git lfs untrack "*.pdf"
git add .gitattributes
git commit -m "Stop tracking PDFs with Git LFS"
Step 2: Migrate files out of LFS
git lfs migrate export --include="*.pdf"
This rewrites Git history and replaces pointers with real PDFs.
Step 3: Force push rewritten history
git push origin --force
After this:
- PDFs are real Git files
- No LFS dependency
- Files open everywhere
Verifying the Fix
file *.pdf
Expected result:
PDF document
And:
git lfs ls-files
Should return nothing.
Pros and Cons of Git LFS (The Honest Take)
Git LFS is Great When:
- Files are large (10MB+)
- Files change frequently
- Repo is long-lived
- Team is technical
- CI/CD understands LFS
Examples:
Git LFS is a Bad Idea When:
- Files are small documents
- Repo is personal or archival
- Users download ZIPs
- Offline access matters
- You want zero setup friction
PDFs, certificates, and documents fall into this category.
The Lesson
Git LFS is not “bad”.
But it is easy to misuse.
If you store documents:
Prefer plain Git
Accept slightly larger repo size
Avoid hidden dependencies
The cost of LFS complexity is often higher than the storage it saves.
Final Rule of Thumb
Code & text → Git
Small documents → Git
Large binaries → Git LFS
Personal docs repo → Never Git LFS