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. Our Large Media plugin has several requirements to work correctly and those are listed here.
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.
Third, 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 first 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. Do to this, run the following command (in the base directory of the
Then you what see in your command line should look similar to this:
$ 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 (your versions could be newer for example - which is expected), then there is something missing.
To resolve the issue, 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 2.6.4 or above. Refer to our CLI docs for information on installation, authentication, and linking your local repository clone to your Netlify site.
- Installed the Netlify Large Media plugin for Netlify CLI.
Installing the Netlify Large Media plugin can be done by running the following commands in the base directory of your
netlify plugins:install netlify-lm-plugin netlify lm:install
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:
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):
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.
.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!
If there are other questions about this, comments are welcome below!