Diagnosing GitKraken Git LFS Upload Failures

Recognizable Condition

When you try to commit a large file in GitKraken you may see an error dialog that reads:
Large files detected; please run 'git lfs install'.
Alternatively the commit succeeds but the repository ends up containing LFS pointer files (text blobs that reference the actual data) instead of the binary content. This indicates the LFS workflow is not functioning correctly.

Cause / Diagnostic Table

Possible Root Cause	Typical Symptoms
.gitattributes missing or incorrect	Large files are not marked for LFS; GitKraken treats them as normal Git objects.
git‑lfs not installed or not initialized in the repo	Commit aborts with the "please run 'git lfs install'" message.
LFS server URL misconfigured	Upload attempts fail silently or return 404/403 errors.
Network or firewall blocking LFS traffic	Upload stalls, timeouts, or no data reaches the server.
LFS cache corrupted or incomplete	Pointer files remain after a fetch; "git lfs ls-files" shows files as "pointer".

Ordered Checks

1. Verify .gitattributes

   Run cat .gitattributes in the repo root. It should contain a line that matches the file type you are pushing, e.g.:

   *.mp4 filter=lfs diff=lfs merge=lfs -text
   

   If the pattern is missing, add it and commit the change.

2. Confirm git‑lfs installation

   Execute git lfs install --force from the repo. This ensures the local Git client is configured to use LFS. Verify with:

   git lfs env
   

   You should see git-lfs/2.13.3 (or newer) and git config --show-origin lfs.* entries pointing to the repo.

3. Check the LFS server URL

   Inspect the configuration:

   git config --get lfs.url
   

   If the output is empty or points to a wrong host, set it with:

   git config lfs.url https://YOUR_LFS_SERVER/v1/objects
   

   Replace YOUR_LFS_SERVER with the actual domain. In GitKraken, this can also be set under Repository Settings → Git LFS URL.

4. Test connectivity to the LFS server

   Use curl or a browser to hit the LFS endpoint. For example:

   curl -I https://YOUR_LFS_SERVER/v1/objects
   

   A 200 OK indicates the server is reachable. If you get a 403 or timeout, check corporate proxies or firewall rules. GitKraken can be configured to use a proxy via Preferences → Git → HTTP Proxy.

5. Inspect and repair the LFS cache

   List tracked LFS files:

   git lfs ls-files
   

   If the list shows pointer instead of local, the object is missing. Clear the cache:

   git lfs prune
   

   Then fetch again:

   git lfs fetch --all
   

   This downloads all LFS objects referenced by the repo.

Fixes Tied to Findings

• Missing .gitattributes: add the correct pattern, commit, and push.
• git‑lfs not installed: install the LFS binary for your OS (e.g. brew install git-lfs on macOS) and run git lfs install.
• Wrong LFS URL: update the config in GitKraken or via git config as shown above.
• Network blockage: open port 443 for HTTPS or route traffic through a VPN. Verify with curl -v https://YOUR_LFS_SERVER/v1/objects.
• Corrupted cache: prune and refetch as described.

Escalation Criteria

If after performing the ordered checks the commit still fails, consider:

• Check the hosting service’s LFS quota and usage. Some platforms (GitHub, GitLab, Bitbucket) impose per‑repo or per‑account limits.
• Examine server logs if you control the LFS endpoint. Look for authentication failures or size restrictions.
• Verify that GitKraken’s internal file size limit (default 100 MB for the UI) is not blocking the upload. For larger files, use the command line or a different client.
• Contact the service’s support team with the error output from git lfs env and the output of curl -v for diagnosis.

Practical Verification

After applying fixes, run:

git lfs ls-files
# Should show files as "local" or "remote" but not "pointer"

git lfs fetch --all
# Ensure no errors

Then attempt the commit again in GitKraken. The status bar should show a successful push without the LFS error. If the error persists, double‑check that the .gitattributes entry exactly matches the file extension and that the file size is within the hosting service’s limits.

Limitations & Caveats

• GitKraken’s UI may cache old configurations; a restart of the application can be necessary after changing global Git settings.
• Corporate proxies may require http.proxy entries in both Git and GitKraken settings.
• Large files exceeding the hosting provider’s quota will still fail even if LFS is configured correctly.

Concrete Example

Suppose you are adding a 150 MB video file demo.mp4 to a GitKraken repo hosted on GitHub. The steps would be:

1. Add to .gitattributes:

   *.mp4 filter=lfs diff=lfs merge=lfs -text
   

2. Commit the .gitattributes change.
3. Run git lfs install and confirm with git lfs env.
4. Check git config --get lfs.url. For GitHub it should be https://github.com/owner/repo.git/info/lfs. If not, set it.
5. Push the video: git push origin main. GitKraken will show the upload progress. If it stalls, run curl -I https://github.com/owner/repo.git/info/lfs to verify connectivity.

After a successful push, git lfs ls-files will list demo.mp4 as remote and the file will be stored in the LFS cache.

Conclusion

Large‑file uploads in GitKraken hinge on a correctly configured .gitattributes, an installed and initialized Git LFS client, a valid LFS server URL, and open network paths. By following the ordered checks above, you can quickly isolate the root cause and apply the appropriate fix. When all else fails, verify quotas and server logs, and involve the hosting service’s support.