Docker Credential Helper Not Working — How to Fix "credentials store not initialized" Error

So I was setting up a new dev machine at like 11pm, running docker push to get an image up to Docker Hub, and I get hit with this:

Error saving credentials: error storing credentials - err: exit status 1, 
out: `credentials store not initialized`

Awesome. Really love seeing that after a long day. The Docker credential helper configuration had gone sideways somewhere between installing Docker Desktop and setting up my config manually. And honestly, this is one of those errors that looks scarier than it is — but it can also send you down some weird rabbit holes if you don't know what's actually going on.

Let me explain what's happening and how to get past it.

Why This Happens in the First Place

Docker uses a credential helper system to store your registry login info securely — instead of just dumping your password in plain text inside ~/.docker/config.json (which, yes, was a thing). The credential helper offloads that to your OS keychain or a dedicated secrets manager like pass on Linux or wincred on Windows.

The problem shows up when your config.json is pointing to a credential store that either doesn't exist, hasn't been initialized, or flat-out isn't installed. This happens a lot when you:

  • Install Docker Engine on Linux without Docker Desktop (which would normally handle this for you)
  • Copy a config file from another machine
  • Upgrade Docker and something gets reset
  • Set up a CI/CD environment and wonder why credentials aren't persisting

I've seen this a hundred times on fresh Ubuntu servers especially. The config file exists but the helper binary it's referencing is just... not there.

Here's what a broken ~/.docker/config.json typically looks like:

{
  "credsStore": "desktop-linux"
}

That credsStore value is telling Docker to use docker-credential-desktop-linux — which only exists if you have Docker Desktop installed. If you're on a headless server or stripped-down environment, that binary doesn't exist and Docker just throws its hands up.

Fix 1: Remove or Update the credsStore Entry

The fastest fix — and honestly what solves it 80% of the time — is to just edit your config.json and either remove the credsStore line or replace it with something that actually exists on your system.

nano ~/.docker/config.json

If you're okay with Docker falling back to base64-encoded credentials stored in the config file itself (totally fine for personal machines or isolated environments), just delete the credsStore line entirely. Your file should look something like:

{
  "auths": {}
}

Then run docker login again. It'll store your credentials locally in that file. Not the most secure option for production, but it works and it stops the error cold.

Fix 2: Install the Correct Credential Helper Binary

If you actually want the secure credential storage (and you probably should in any shared or production environment), you need to install the right helper. On Linux, docker-credential-pass is the most common one people use.

First, grab the binary from the GitHub releases page or install it directly:

# Check latest version at https://github.com/docker/docker-credential-helpers/releases
VERSION=0.8.1
curl -fsSL "https://github.com/docker/docker-credential-helpers/releases/download/v${VERSION}/docker-credential-pass-v${VERSION}.linux-amd64" \
  -o /usr/local/bin/docker-credential-pass
chmod +x /usr/local/bin/docker-credential-pass

Now here's where it gets tricky — pass itself needs to be initialized with a GPG key before the credential helper can actually use it. A lot of people install the binary and then wonder why it's still broken.

# Install pass
sudo apt-get install pass gpg

# Generate a GPG key if you don't have one
gpg --gen-key

# Initialize pass with your GPG key ID
pass init YOUR_GPG_KEY_ID

You can find your GPG key ID by running gpg --list-keys and grabbing the long hex string. Once that's done, update your config.json:

{
  "credsStore": "pass"
}

Run docker login and you should be good. The credentials will be stored encrypted via your GPG key. Much cleaner.

Fix 3: Use the osxkeychain or wincred Helper on Mac/Windows

If you're on macOS and hitting this issue, it's usually because the osxkeychain helper got disconnected somehow — often after a Docker Desktop update or a migration.

# Verify the helper exists
which docker-credential-osxkeychain

# If it's there, just update your config.json
{
  "credsStore": "osxkeychain"
}

On Windows with Docker Desktop, it should use wincred or desktop-windows automatically. If you've somehow got a mismatched value in there (I've seen people copy Linux configs onto Windows machines — don't do that), just reset it:

{
  "credsStore": "wincred"
}

And then re-run docker login to re-authenticate.

Fallback: Nuke the Config and Start Fresh

Sometimes the config file is just mangled enough that it's easier to start from scratch. This is especially true if you've got weird key conflicts or invalid JSON hanging around in there.

mv ~/.docker/config.json ~/.docker/config.json.bak
docker login

Docker will recreate the config file fresh. You'll lose any saved auth tokens but that's honestly not a big deal — just log back in to your registries. I usually keep the backup around for like a day just in case, then delete it.

One thing worth mentioning — if you're doing this in a Dockerfile or CI pipeline context, you probably don't want credential helpers at all. Just use environment variables or a secrets manager and pass credentials at build/run time. Baking credential helper config into a container image is a headache I wouldn't wish on anyone.

Anyway, hope this saves you the hour I lost staring at that error the first time I saw it. The Docker credential helper system is genuinely useful once it's set up right — it just has almost zero helpful error messaging when something's off.

Related: How to Fix Docker Error Getting Credentials (And Why It Keeps Happening)

๋Œ“๊ธ€

Zoho IMAP Settings: The Complete Fix When Your Email Stops Syncing

Quick Summary Zoho IMAP breaks more often than it should, and the error messages are genuinely useless. The fix is usually a combination of using the right server address, enabling IMAP inside Zoho Mail's settings, and generating an app-specific password. This guide covers the exact steps for Outlook, iPhone, Thunderbird, and Android so you stop going in circles. Photo by Fotis Fotopoulos on Unsplash So your Zoho Mail stopped syncing. Emails aren't coming in, your phone shows a spinning indicator forever, or Outlook throws some vague authentication error and you have no idea what changed. Sound familiar? I've seen this exact situation probably thirty times across different clients, and every single time the person swears they didn't change anything. And honestly? They usually didn't. Zoho changed something on their end, or an app update reset a setting, or someone enabled two-factor authentication without realizing what that does to third-party mail clients. The...

Zoho Mail IMAP Configuration: Exact Settings That Work First Time

Quick Summary Getting Zoho Mail IMAP to work in Outlook or Thunderbird is not as straightforward as Zoho's docs make it sound. The port numbers, SSL settings, and app password requirements catch almost everyone off guard the first time. Here are the exact settings and steps that actually work, without the back-and-forth with support. Photo by Fotis Fotopoulos on Unsplash Last month I spent almost two hours on a Friday afternoon helping a new employee get Zoho Mail working in Outlook. Two hours. The settings look simple on paper — and honestly, they are — but there are two or three specific things that Zoho just does not make obvious, and if you miss any one of them, you get a generic authentication error that tells you absolutely nothing useful. Sound familiar? The thing is, I've set up Zoho IMAP maybe forty times across different clients and different mail apps. Outlook, Thunderbird, Apple Mail, even some third-party Android clients. And every single time, someone new come...

์ด ๋ธ”๋กœ๊ทธ ๊ฒ€์ƒ‰

Magnesium Glycinate vs Magnesium Citrate: Which One Actually Fixed My Sleep

Quick Summary I spent months trying different magnesium forms after my sleep fell apart, and the difference between glycinate and citrate is way bigger than I expected Glycinate is the gentler, slower option great for sleep and anxiety, while citrate works faster but comes with some digestive surprises nobody warns you about If you're confused about which one to take, this breaks down exactly what each form does and who should actually be using it Photo by Anshu A on Unsplash About two years ago I hit a wall. I was waking up at 3am every single night, my legs felt restless, and I was grinding my teeth so bad my jaw hurt in the morning. My doctor ran some basic labs, everything came back "normal," and I left that appointment feeling completely dismissed. A friend of mine — she's really into functional nutrition — casually mentioned that I might just be magnesium deficient. I kind of rolled my eyes at first. It sounded like one of those wellness buzzwords people throw...
↑