[Support Guide] Troubleshooting your Netlify Large Media Configuration

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. :slight_smile: Here are the requirements for our Large Media plugin to work correctly.


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 version in 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:


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

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:

  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.)


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!


I have followed all the steps as mentioned in the docs and did run the troubleshoot, but still it is not showing the files in Netlify Large media.

We’d be happy to help debug, but we’d need some more details. Perhaps you could provide a link to a page that isn’t working as you expect, with a description of the missing asset. Something like: “On my site https://mysite.com/resume, I have large media set up for the referred asset file.pdf. You can see in the browser dev console that it gets a 404” would be most helpful!

Hi there, I have followed all the steps, I got the files looks “good”, but when i do git push it asks me user/password and the one I use to login to netlify doesn’t works.

It looks like some problem with git-credentials-netlify but I don’t know how to fix this.

Any idea?

thank you, Enrico

I’m having the same problem as ilsasdo

When i try to push to the repo it asks me for the credentials

user@1c6910b52379:/app/travel-cecil$ git push
Username for 'https://mysite.netlify.com': my@email.com
Password for 'https://my@email.com@mysite.netlify.com': 

I tried logging into my netlify credentials, and the one created when it was from template. Do you know what these credentials are asking for? No credentials seem to work.

1 Like

Doing some further research the issues seems like this

I get pretty much the exact same error

user@1c6910b52379:/app/test-netlify$ DEBUG=1 GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push origin master
05:39:24.495448 git.c:344               trace: built-in: git push origin master
05:39:24.496352 run-command.c:646       trace: run_command: unset GIT_PREFIX; ssh git@github.com 'git-receive-pack '\''palidanx/test-netlify.git'\'''
05:39:25.579890 run-command.c:646       trace: run_command: .git/hooks/pre-push origin git@github.com:palidanx/test-netlify.git
05:39:25.586555 git.c:576               trace: exec: git-lfs pre-push origin git@github.com:palidanx/test-netlify.git
05:39:25.586652 run-command.c:646       trace: run_command: git-lfs pre-push origin git@github.com:palidanx/test-netlify.git
05:39:25.610646 trace git-lfs: exec: git 'version'
05:39:25.623785 trace git-lfs: exec: git '-c' 'filter.lfs.smudge=' '-c' 'filter.lfs.clean=' '-c' 'filter.lfs.process=' '-c' 'filter.lfs.required=false' 'rev-parse' 'HEAD' '--symbolic-full-name' 'HEAD'
05:39:25.632790 trace git-lfs: exec: git 'config' '-l'
05:39:25.635964 trace git-lfs: exec: git 'config' '-l' '-f' '/app/test-netlify/.lfsconfig'
05:39:25.642256 trace git-lfs: pre-push: refs/heads/master 1d7147f4baee3ec84a0221f1220962b2bc6ff5e7 refs/heads/master 8c2a7ce2a10112c1855e520a6a94247f64d2ee32
05:39:26.783783 trace git-lfs: creds: git credential fill ("https", "00af26a7-362b-4b16-af49-da645b3832c6.netlify.com", "")
05:39:26.787197 git.c:344               trace: built-in: git credential fill

And the authentication fails. When you try to enter credentials

Username for 'https://00af26a7-362b-4b16-af49-da645b3832c6.netlify.com': sdf
Password for 'https://sdf@00af26a7-362b-4b16-af49-da645b3832c6.netlify.com': 
05:57:50.552357 trace git-lfs: Filled credentials for https://00af26a7-362b-4b16-af49-da645b3832c6.netlify.com/.netlify/large-media
05:57:50.552938 trace git-lfs: HTTP: POST https://00af26a7-362b-4b16-af49-da645b3832c6.netlify.com/.netlify/large-media/locks/verify
> POST /.netlify/large-media/locks/verify HTTP/1.1
> Host: 00af26a7-362b-4b16-af49-da645b3832c6.netlify.com
> Accept: application/vnd.git-lfs+json; charset=utf-8
> Authorization: Basic * * * * *
> Content-Length: 36
> Content-Type: application/vnd.git-lfs+json; charset=utf-8
> User-Agent: git-lfs/2.7.1 (GitHub; linux amd64; go 1.11.5)
{"ref":{"name":"refs/heads/master"}}05:57:51.517497 trace git-lfs: HTTP: 401

It’s oddly attempting trying to auth against the website endpoint.

It seems like when netlify login happens it isn’t storing the credential correctly?

i have the exact same issue , did you manage to find a fix?

All the troubleshooting steps show correct results, and i followed all the steps in the docs. But still nothing shows up in the Large Media section of netlify. I also get a 401 when trying to acess my “(…).netlify/media” . What may be causing that?

The time on my clock was around (11’o clock), when I started facing the issue.

Yes, the FIX was very easy but it took me almost 8 hrs.

Here’s what I did,

  1. Turn off my laptop
  2. Take a good nite sleep
  3. Woke up
  4. Open the app.netlify.com
  5. and there you will find the fix

This is no joke, it really did work for me.

When I didn’t found any other solution, I give followed the above same steps.

What could be possible problem?
When we initialize Netlify Large Media in a site and upload few bigger size files, it seems like the netlify server is takes a longer time to process those files and show them.

Hi, @palidanx. Would you please try using netlify logout followed by netlify login to see if this restores the credentials? And would you please confirm here if that works or not?

If it doesn’t resolve it, would you please open a support case with us?

@yarilabs, would you also try the netlify logout followed by netlify login steps? And also open a support case with us if this doesn’t resolve the issue?

Actually I think I made a mistake in the process and forgot to run netlify lm:install As a review this is what I ran

#cd to git base directory
netlify lm:setup
netlify lm:install
git lfs track "*.jpg" "*.png"
git push
1 Like

I eventually solved, even if it’s not totally clear what did the trick.

The last thing i changed was this: I noticed an error from git-credential-helper (which I also have installed manually): Aborting Netlify credential helper execution" error="open $home\\.config\\netlify.json:

so I’d copied the original file $home/.netlify/config.json to .config/netlify.json … yes… filename and directory switched… fairly odd…

hi @viviangb, would you mind pulling this out and posting a new thread in the #netlify-platform:netlify-large-media category? We’ll also need to know things like what your instance name (netlify URL) is, what you’ve already tried, and so on. thanks!

Hey, I am having some issues using large media for images, all looks good following the commands above. I can see the image in the correct directory in the sites large media section. However on the preview site I get a 404 for the image, can’t see any issues in the build logs etc.

My latest deploy

Hi, @danjmurphy92. I opened a support ticket for this and I’ll also follow-up in this other topic (which looks like the “original” topic):


I solved this same problem by:

  1. Using nvm to manage my packages instead of npm

  2. Adding a git config to address an error message ( Remote "origin" does not support the LFS locking API. Consider disabling it.) that I would get when Ctrl-Cing my way out of entering a username and password. So consider running:

git config lfs.https://d7dg5c72-5439-b0eg-46a4-dgfcd61d9936.netlify.com/.netlify/large-media.locksverify false

1 Like

I solved credential problem by manually added to .git/config:
helper = netlify


it worked for me too. I manually added in .git config this:

[credential "https://your-netlify-website-name.netlify.com"]
helper = netlify

Reference: Git - gitcredentials Documentation

1 Like