Startup post-mortem on AWS Cognito: fragmented docs, Amplify v6 rewrite, immutable attributes

A first-person account of building startup authentication on AWS Cognito has reached the front page of Hacker News, with its author concluding that he would not choose the service again. The post, published by developer Josh Karamuth on his personal blog, is less a rant than a checklist of concrete failure modes, and it ends with practical advice for teams currently evaluating the service.

According to the post, the team picked Cognito because it was already part of their AWS setup and because the free tier covers the first 50,000 monthly active users. The author had shipped authentication before, using Auth0, Firebase Auth, and a hand-built JWT system, and expected the work to be routine. What followed, he writes, was a series of structural problems rather than one-off bugs.

Documentation aimed at too many audiences

The first complaint is the documentation. The author argues AWS is writing for several audiences at once — enterprise architects who want protocol-level detail, web developers who just need a login form, and mobile developers who need native SDK guidance — and that the result serves none of them well. Pages assume prerequisite reading that is never clearly signposted, and code samples mix at least three generations of tooling: the older JavaScript SDK, the Amplify v1 API, and the raw AWS SDK, often without saying which one an example targets. Working out which library a snippet belongs to becomes an exercise in inspecting import statements, he says.

A version bump that forced a rewrite

The costliest issue involved Amplify, AWS's JavaScript client library for Cognito. The team built and shipped their sign-in flow on Amplify v5; when the author later upgraded to v6, he found the release had rearchitected how the library talks to Cognito rather than adjusting a few method signatures. Functions the team's UI depended on had been removed or replaced, and the migration guide did not fully bridge the gaps. Working, production-tested authentication code had to be rebuilt rather than incrementally refactored.

Cloud-only testing and limited UI control

Because Cognito is a managed cloud service, the author notes, there is no supported way to run a faithful local instance for offline testing. Community emulators and plugins exist but vary in maintenance and accuracy, which in his case produced a local mock that behaved differently from the real thing — bugs passed local checks and appeared in staging, defeating the point of local development.

The hosted login UI drew similar criticism. Beyond swapping the logo and adjusting some CSS in the console, branding options are limited, and the layout stays recognisably AWS. The common community workaround is to drop the hosted UI and build a custom interface on the SDK, which cuts into the value of the managed offering.

The email-attribute trap

The post's sharpest cautionary tale concerns a setup mistake. The app needed email-only sign-in, and the author discovered that Cognito treats email differently depending on whether it is configured as a core attribute, an alias, or a custom attribute, with the relevant options spread across multiple console screens and their interdependencies left unexplained. After configuring one attribute as custom where a standard one was needed, he learned that user pool attributes are permanent once created. The fixes are deleting the pool and starting over, or scripting a migration of live users into a correctly configured pool, password resets included — unattractive options for a product already in production.

Why it matters

Authentication is a poor place to trade developer experience for ecosystem convenience, the author argues. The free tier stops looking cheap once the engineering hours spent fighting documentation and rewriting code around breaking library changes are counted; he estimates the time lost to debugging could have paid for several years of a commercial auth provider. His recommendation for teams evaluating Cognito is to build a small but nontrivial proof of concept first — one that exercises custom attributes, email verification, and a password reset flow — and to time the effort. He also discloses that he is still running Cognito on the project, because it is now too embedded to remove. That is part of the lesson: auth choices made early are expensive to reverse, so the evaluation phase deserves more weight than 'it's already in the ecosystem' usually gets.