Last reviewed & updated by Netlify Support on May 25, 2022
So, you are trying to use the Netlify Large Media feature and it isn’t working as expected. Where do you begin troubleshooting?
Well, we’re happy to help. 
Here are the requirements for our Large Media plugin to work correctly.
Requirements
The first two requirements are:
- access to a Netlify account with permissions for this site
- the site is deployed via a tracked git repo (not manual deployments)
Netlify Large Media is built using Git Large File Storage (LFS). This means, if you aren’t using git, Netlify Large Media won’t work.
Much of what follows involves using git on the command-line interface (or CLI).
If you don’t know how to use git via the CLI, please research that before proceeding with the rest of this topic.
So, if you can log into Netlify and you are using git on the CLI, what’s next?
Is Netlify Large Media installed and working?
Next, we will check to see if Large Media is installed. To do this, run the following command (in the base directory of the git repo):
netlify lm:info
You should see output in your command line which looks similar to the following:
$ netlify lm:info
✔ Checking Git version [2.20.1]
✔ Checking Git LFS version [2.7.0]
✔ Checking Git LFS filters
✔ Checking Netlify's Git Credentials version [0.1.8]
If you don’t see results similar to those above (the versions may differ), then there is something missing.
In this instance, you will need to resolve the missing requirements. Those are:
- Git LFS version 2.5.1 or above, installed on your local machine. You can run
git lfs versionin your terminal to see if you have a valid version installed. If not, follow the installation instructions on the Git LFS website. - Netlify CLI version 3.8.0 or above. Refer to our CLI docs for information on installation, authentication, and linking your local repository clone to your Netlify site.
All the requirements are installed and it still isn’t working!
Hmmm. Well, if all the requirements are met, it is time to check the details.
First, confirm that all the required versions are correct using this command, again, in the base directory of the git repo:
netlify lm:info
If that command shows versions equal to or newer than the required versions, now it is time to check the following files (again, they are found in the repo base directory):
- .gitattributes
- .lfsconfig
- .gitignore
In these files, look for common issues. If .gitattributes is empty, for example, the files are not being tracked by Git LFS. The solution would be to add files for tracking like so:
git lfs track <filename-or-filenames-here>
There are more details about this in our documentation here.
For the file .lfsconfig, check to see if the URL in that file ends with netlify.com/.netlify/large-media. Often people use another LFS provider like Github before switching to Netlify Large Media. Because of this, the previous LFS provider’s URL can be in .lfsconfig instead of Netlify’s.
And why .gitignore? Well, one common scenario is that large media files are being ignored here because, possibly, they previously were not being tracked by git. If so, then removing the .gitignore rules which ignore those files can be the solution!
Common issues
Common issue: The Git Credential Helper isn’t installed in the Git config
When your Git LFS service isn’t Large Media, whatever authentication you are using for your Git host (GitLab, GitHub, Bitbucket) is also used for Git LFS. However, when you move to Large Media, for any Git LFS tracked files, now Netlify’s authentication is used.
For that authentication to work something called the “Netlify Git credential helper” is installed. This is installed to the user’s home directory. Here are example locations on Linux and MacOS respectively:
/home/username/.config/netlify/helper/
/Users/username/.netlify/helper/
You can tell if Git is configured to use the helper by checking with the command git config -l. For example, here is me testing it below:
$ git config -l | grep netlify
include.path=/home/username/.config/netlify/helper/git-config
credential.helper=netlify
lfs.https://a1ce8601-a525-4e47-b147-29e241fe546e.netlify.app/.netlify/large-media.access=basic
Above, we see it is working. If it isn’t working for you, you can install it manually.
To install it manually, first find the location of the file (which was /home/username/.config/netlify/helper/git-config in my case). Then add these two lines to ~/.gitconfig:
[include]
path = /home/username/.config/netlify/helper/git-config
Of course, you will need to use the correct path for where the helper was installed for you. After you save the file with those changes running git config -l again should show the helper being used.
Common issue: The Git Credential Helper isn’t installed for the shell
You should confirm that the shell helper is installed as well. When you first run netlify lm:setup, the following is added to your .bashrc (if your shell is bash):
# The next line updates PATH for Netlify's Git Credential Helper.
if [ -f '/home/username/.config/netlify/helper/path.bash.inc' ]; then source '/home/username/.config/netlify/helper/path.bash.inc'; fi
On MacOS, the line might look like this (the line added has evolved and this is an older example below):
# Netlify Large Media
. /Users/username/.netlify/helper/path.bash.inc
So, if it is missing, how do you fix it? You need the following details to resolve this issue:
- the path were the credential helper is found
- the configuration file for the shell you are using
Using the information above, you then need to add the correct command to load the correct helper for your shell into the correct shell configuration file. If you have any questions about how to do this, we need the following details:
- the path were the credential helper is found (same as above)
- what operating system you are using
- what shell you are using
If you tell us those three details, we should be able to help you get the credential helper working in your shell environment.
Common issue: I deployed but my files are not working.
Missing files common cause #1: The files are not in the publish directory.
Just because you are using Large Media doesn’t mean that anything else about deploying has changed.
Always, for any deploy at Netlify, any file you want to deploy must be found in the site’s publish directory when the build is finished. Only those files become part of the deployed site.
If you have files and they are not placed in the publish directory, you can access them during the build but only the files in the publish directory become part of the deployed site.
The same is true of Large Media. Just putting files into the repo - doesn’t magically publish them to the site at Netlify. They are only published if they are part of a deploy and, again, only if the files are placed somewhere in the publish directory.
Missing files common cause #2: The files were not pushed to Large Media.
The second most common cause is that the files simply don’t exist in the Large Media Git LFS service yet.
This happens because your Git client thinks the Git LFS service already has the files (meaning that the Git client doesn’t “know” that the Git LFS service changed). If the files are not modified, Git has no reason to upload them to Git LFS again (because it doesn’t send unchanged files). The end result is that the files exist for you locally but not at Large Media.
The solution is to force Git to send the files to Large Media (and this works for any Git LFS service). You can do so in your repo directory using this command below:
git lfs push --all origin
In many cases, this fixes Large Media assets not working. Also, you don’t even need a new deploy with this fix. The push alone should simply make the data available in Large Media and the site will start working. (If not do try a new deploy but, again, in most cases that won’t be required.)
Follow-up
If there are any questions about anything in this support guide, please feel free to create a new topic for your question and our support team will be happy to assist!