I was three days into setting up authentication for our startup when I realized something was wrong. Not "I missed a semicolon" wrong. More like "I followed every step in the documentation and the password reset flow still redirects to the wrong place" wrong.

I had the docs open in twelve tabs. I had copy-pasted the code samples. I had even watched a tutorial from someone who sounded like they’d been through this exact nightmare before.

Here’s the thing. I’ve implemented authentication before. I’ve wrestled with Auth0, tamed Firebase Auth, and even rawdogged a custom JWT system that I’m not proud of but it worked.

So when our startup needed auth and the team leaned toward Cognito because "it’s already in the AWS ecosystem and the first 50,000 monthly active users are free," I thought, how bad could it be? I regret everything. The Documentation Was Written for Five Different People at Once Reading Cognito docs feels like someone took three separate manuals, threw them in a blender, and then sprinkled in some outdated Stack Overflow answers for flavor. AWS is trying to serve too many audiences simultaneously.

You’ve got the enterprise architect who wants to understand the underlying identity protocols. You’ve got the frontend developer who just wants a login form. You’ve got the mobile developer who needs native SDKs.

And the docs try to be everything to everyone, which means they end up being useful to exactly nobody. I’d search for "Cognito custom attribute validation" and land on a page that starts with a paragraph about directory schemas that assumes I’ve already read four other pages I didn’t know existed. There’s no clear linear path.

It’s just a web of hyperlinks and prayers. And the code examples. Oh, the code examples.

Half of them are for the old Java Script SDK. Some reference the Amplify v1 API. Others use the raw AWS SDK.

The docs don’t always clearly tell you which version they’re talking about, so you’re left playing detective with import statements. The Day Amplify v6 Betrayed Me Speaking of versions. Let me tell you about the Java Script library situation, because this one genuinely caught me off guard.

When we started building, Amplify was on version 5. I wrote our auth flow, tested it, committed it, moved on to other features. A few weeks later, I came back to fix a bug and noticed some deprecation warnings in the console.

No problem, I thought. I’ll just update to the latest version. Friends.

Amplify v6 didn’t just change a few method signatures. It fundamentally rearchitected how you interact with Cognito. Functions I had built entire UI flows around were gone.

Replaced. Vanished. The migration guide existed, technically, but it felt more like a treasure map with half the landmarks missing.

I rewrote the code. Not refactored. Rewrote.

Authentication logic that was working perfectly fine in production had to be rebuilt because the library maintainers decided the old API was no longer the blessed path. That’s not an upgrade. That’s a hostage situation.

Local Development is a Special Kind of Pain Here’s a fun fact about Cognito: it’s cloud-based. I know, shocking. But what that means practically is that you can’t just spin up a local instance and test your auth flows offline.

You’re always hitting actual AWS endpoints. Now, there are tools like the serverless-offline plugin and local Cognito emulators that try to bridge this gap. But they’re community projects with varying levels of maintenance and fidelity.

The official story from AWS is basically "test against the cloud," which is great advice unless you’re on a plane, or your internet is spotty, or you just want fast iteration cycles without waiting for network round trips. I spent an embarrassing amount of time setting up a local mock that didn’t quite match the real thing, which meant bugs would slip through locally and show up in staging. The whole point of local development is catching issues early, and Cognito actively works against that.