Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 37 ยท Practice and Review

Common Microservices Mistakes and Anti-Patterns

Spot the distributed monolith, chatty services, shared databases, shared libraries and nano-services, and learn the fix for each, with a small detector you can run.

Most failed microservice projects do not fail because the pattern is bad. They fail because the team kept the coupling of a monolith and added the cost of a network. The same handful of mistakes appear again and again, in companies of every size, and each one has a recognizable smell and a known fix.

This lesson names the mistakes, shows how to notice them, and says what to do instead. At the end you will run a small detector over a described system. The detector is a stand-in: it reads a hand-written description of services and calls, not real traffic, and it uses simple thresholds that you would tune for your own system. Real tools read tracing data and deployment history, but the questions they ask are these.

The usual suspects

Distributed monolith Services that must deploy together.
Chatty services Dozens of calls for one request.
Shared database Many owners of the same tables.
Shared libraries One upgrade forces many redeploys.
1 / 2

The distributed monolith

A distributed monolith has many deployable parts but behaves like one program: you cannot release service A without releasing B and C, a change to one data shape breaks five callers, and an outage in one service takes everything down. You pay for network calls, partial failure and operations work, and you get none of the independence.

Symptoms:

  • Release notes say "deploy in this order".
  • A single feature needs pull requests in four repositories.
  • Staging only works when all services are at matching versions.
  • Services call each other in long synchronous chains (A calls B calls C calls D).

Fixes: draw boundaries around business capabilities, not technical layers (Finding Boundaries with Domain-Driven Design); make contracts backward compatible so versions can differ (API Versioning and Evolving Contracts); replace long synchronous chains with events where the caller does not need the answer (Asynchronous Messaging and Events); and if two services always change together, merge them. Merging is a legitimate repair, not a defeat.

Chatty services

A service is chatty when one user request triggers many small calls between services. Each call adds latency, a chance of failure and load, and the effects multiply. If each call has a 1 percent chance of failing, a request that needs 20 sequential calls fails in about 18 percent of cases.

The classic form is the N+1 call: fetch a list of 50 orders, then call the product service once per line item. Fixes:

  • Add batch endpoints (GET /products?ids=1,2,3).
  • Let the caller send what the callee needs, or include data in events so the callee already has a local copy (Database per Service and Data Ownership).
  • Aggregate at an API gateway or Backend for Frontend, in parallel, instead of one chain (API Gateway and Backend for Frontend).
  • If two services talk constantly to each other, they probably belong together.

The shared database

Two services reading and writing the same tables are coupled through the schema. A column rename in one breaks the other, nobody can tell who is allowed to change what, and you cannot deploy or scale them independently. It is the most common reason a microservice system turns into a distributed monolith.

Fix: one owner per table. Other services use the owner's API or subscribe to its events and keep their own copy of the few fields they need. This is covered in depth in Database per Service and Data Ownership. It does not require separate database servers on day one: separate schemas with separate credentials already enforce the rule, and are far cheaper to run.

SQL
-- Read-only illustration: ownership enforced with permissions, one server
CREATE USER orders_svc  WITH PASSWORD '...';
CREATE USER billing_svc WITH PASSWORD '...';

GRANT ALL ON SCHEMA orders  TO orders_svc;
GRANT ALL ON SCHEMA billing TO billing_svc;
-- billing_svc has no access to the orders schema at all.

Shared libraries that couple services

A shared library is fine for technical helpers: logging, a retry function, an HTTP client wrapper. It becomes a trap when it holds business code or shared data models. A change to common-models then requires every service to upgrade, test and deploy, which is a lockstep release in disguise.

Rules of thumb:

  • Share infrastructure code, not domain code.
  • Version libraries and let services upgrade on their own schedule; support old versions for a while.
  • Prefer contracts (an API schema, a message schema) over shared classes. A service should be able to read a message with its own small class.
  • Duplication of a few lines between services is cheaper than coupling them. This is the microservice version of "a little copying is better than a little dependency".

Nano-services and premature splitting

The opposite mistake is splitting too far. A nano-service does so little that its overhead (a repository, a pipeline, a dashboard, an on-call rotation, network hops) outweighs its value. Having 60 services for a team of 8 is a common version.

Fix: start from a modular monolith, split when a boundary has proven stable and a real need exists (a different scaling profile, a separate team, an independent release rhythm), and merge services that never change independently. Remember that the unit of a service is "something a team can own", not "one function".

More mistakes worth knowing

  • No observability. Without correlation ids, structured logs and traces, a failed request is a murder mystery across ten services (Observability: Structured Logs and Metrics, Distributed Tracing).
  • No timeouts or retry limits. A slow dependency then ties up every thread, and naive retries multiply the load (Timeouts, Retries and Exponential Backoff).
  • Assuming distributed transactions work like local ones. Use sagas and idempotent handlers (Sagas).
  • Starting with the hard parts. Extracting the core order flow first is riskier than starting with a loosely coupled capability (Project: Strangling a Monolith).
  • Ignoring the platform. Without automated deploys, health checks and config management, each new service is manual work (Deployment Strategies and CI/CD).
  • Too many languages and stacks with no support from a platform team, so nobody can help another team.

A detector you can run

The stand-in below describes a small system as data: which database each service uses, and which service calls which, with the number of calls one user request causes. Then four plain checks flag the problems from this lesson: a database used by more than one service, a chatty edge (5 or more calls per request), a call cycle (reported once), and a synchronous chain that is too deep (4 or more services in a row). It also flags services with a single endpoint as possible nano-services.

JS Find the anti-patterns in a system description

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the findings as questions, not verdicts. The emailer may be a perfectly good small service with a clear owner, for example, and the cycle might be three names for one concept that should be one service. The tool narrows where to look; the decision is design work.

Fixing chattiness with a batch call

The N+1 problem is easy to measure. This second stand-in prices each call at a fixed 5 ms and compares fetching 12 products one at a time with fetching them in one batch. Real latency varies and calls can run in parallel, but the shape of the saving is the same.

JS N+1 calls versus one batch call

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The batch also fails far less often, because there is only one call that can go wrong. It still has one risk of its own: a batch endpoint needs a sensible maximum size and a clear rule for partial results (some ids missing), or it becomes the new weak point.

When you review a design, ask three questions: Who owns this data? What happens when this call is slow or down? Do these two services always change together? Most of the mistakes above show up in the answers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which situation best describes a distributed monolith?

    The mark of a distributed monolith is coupling: separate deployables with monolith-style dependencies, plus the cost of a network.
  2. 2. What is the cleanest fix for two services sharing the same database tables?

    One owner per table removes schema coupling. Separate schemas with separate credentials can enforce this even on one database server.
  3. 3. A page load triggers 40 calls between services. What is the usual first remedy?

    Fewer, larger calls cut latency and failure probability. More retries or longer timeouts make a chatty design worse.
  4. 4. When does a shared library become an anti-pattern?

    Shared domain code forces lockstep releases. Share technical helpers, and prefer contracts to shared classes.
  5. 5. Why can merging two services be the right repair?

    A boundary should let teams work independently. If it never does, removing it is cheaper than maintaining it.

Summary

  • A distributed monolith has the coupling of one program and the costs of a network. Fix it with better boundaries, compatible contracts and events.
  • Chatty services multiply latency and failure risk. Batch, aggregate, copy needed data or merge.
  • One owner per table. Share data through APIs and events, not the schema.
  • Share infrastructure libraries, not domain code, and prefer contracts to shared classes.
  • Too many tiny services is also a mistake; start with a modular monolith and split for real needs.
  • Detectors give hints; judging them is design work.

Next: Practice Exercises with Solutions.