Fix macOS NSURLErrorDomain error -1012

Authentication failed for a URL request, often due to expired credentials or a server rejecting certificates. Clear the keychain entry or refresh the token.

Quick answer

Clear the stored credential for the server in Keychain Access or delete the app's cached token, then retry.

What's actually happening here is that the system's URL loading machinery — either NSURLSession or a lower-level CFNetwork call — got a response from the server that says "you're not authenticated." The -1012 code is NSURLErrorUserCancelledAuthentication, and it usually means the server rejected the credentials that were automatically supplied from the keychain or from a URL session's internal cache. It's not a DNS problem, not a timeout, not a connection drop — it's an auth failure that your code didn't handle, so the OS surfaced it as a raw error.

You'll see this most often when you're using a tool like curl, a git remote over HTTPS, or a Mac app that talks to a REST API with basic auth or OAuth tokens. A classic trigger: you changed your password on the server, but the keychain still holds the old one. Another: a corporate proxy or VPN that injects a certificate, and the server's SSL chain now looks untrusted to the app.

Before you try anything

Check when the error appears. If it's on a fresh app install or after a macOS update, it's a keychain migration issue. If it's intermittent, you might be dealing with a token that expires and the app didn't refresh it. Don't skip to the nuclear option (deleting all keychain entries) until you've tried the targeted fixes below — nuking the whole keychain will force you to re-enter passwords for Wi-Fi, mail, and every site you've saved, which is a pain.

Fix 1: Remove the specific keychain entry

Open Keychain Access (in /Applications/Utilities).
In the search box, type the hostname of the server you're connecting to — e.g., api.example.com.
Look for an entry named like "Internet Password" or "Web Form Password" with that host.
Right-click it and select Delete. Confirm.
Retry your request. The app will prompt for credentials again, and you can enter the correct ones.

The reason this works is that the keychain is the default credential store for URL requests. When a server returns a 401, CFNetwork looks up a matching keychain item. If it finds one, it automatically sends it. If that credential is stale, the server rejects it again, and some code paths just give up and report -1012 instead of re-prompting. Clearing the item forces a fresh prompt.

Fix 2: If you use git, update the remote URL

Git often caches credentials in the keychain via osxkeychain helper. If you changed your password, the old one is still there.

git config --global --list | grep credential.helper

If you see osxkeychain, run:

git credential-osxkeychain erase <<EOF
protocol=https
host=github.com
EOF

Then on the next git pull, you'll be asked for the new password. For GitHub, you'll need a personal access token, not your account password.

Fix 3: Handle it in code (if you're a developer)

If you're writing an app that uses URLSession, you might see this error when a server requires a client certificate or when the session's URLCredentialStorage has stale data. Override the auth challenge delegate and decide what to do:

func urlSession(_ session: URLSession, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
    if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust {
        // Only do this if you know the server is legit, otherwise it's a security hole.
        completionHandler(.useCredential, URLCredential(trust: challenge.protectionSpace.serverTrust!))
    } else {
        completionHandler(.performDefaultHandling, nil)
    }
}

But note: if the server actually returned 401, this delegate won't fire — you'll get an HTTP status code instead. The -1012 you're seeing is a transport-level auth failure, not an HTTP-level one. So the delegate approach only helps if the server is demanding a client certificate or a TLS renegotiation.

Alternative fixes if the above don't work

Restart the app or service — sometimes a URLSession keeps a background task with the old auth state. Quit and relaunch.
Reboot macOS — rare, but a hung securityd can cause odd auth failures. A reboot clears that.
Temporarily disable the VPN — if a VPN injects a proxy that mangles the auth header, you'll get this error. Test without the VPN.
Check the server's SSL certificate — use curl -v https://host to see if the certificate chain validates. If it fails, you'll get a -1202 error instead, but a server that asks for client certs and then rejects them can produce -1012.

Prevention

The root cause is almost always a stale credential. So the habit that saves you: whenever you rotate a password or a token on any service, immediately delete the corresponding keychain item. For development, consider using URLSessionConfiguration.ephemeral so credentials aren't persisted to the keychain at all — that way you never have a stale entry.

Also, if you're building an app that talks to a server with changing certificates (common in dev environments), set URLProtectionSpace with a longer sessionRequiresTLS and handle the challenge explicitly. But for day-to-day fixes, clearing the keychain entry solves 90% of these errors.

One more thing: if you're on a shared Mac, make sure the keychain item belongs to the right user. I've seen cases where the error persisted because the credential was stored under a different login keychain, and the app was looking in the default one. Check the "Keychain" column in Keychain Access to confirm.