DEV Community: Fazal Mansuri

🛠️ Database Connection Pooling: The Hidden Bottleneck That Can Bring Your Application Down

Fazal Mansuri — Fri, 06 Nov 2026 17:45:44 +0000

Imagine this.

Your application has been running perfectly for weeks. APIs are responding quickly, database queries are working and everything looks healthy.

Then, suddenly:

API requests start taking several seconds.
Some requests time out, while others never seem to complete.
New database operations stop working.
Restarting the application temporarily fixes everything.
A few minutes or hours later, the same problem returns.

You check the database. It's running.

You check the application. No obvious crash.

You check the logs and find something like:

Error: context deadline exceeded
Error: connection pool exhausted
Error: timeout acquiring connection

One possible reason?

Your application has run out of available database connections.

This is where database connection pooling becomes extremely important.

Connection pooling is one of those concepts that developers often configure once and forget about. But an incorrectly configured pool, or connections that are never released, can gradually bring an otherwise healthy application to a halt.

In this article, we'll go beyond what connection pooling is. We'll understand how it works, how connections get stuck, how to reproduce pool exhaustion, how to debug it in a real application and which practices help prevent these problems in production.

We'll use Go's database/sql package for practical examples, but the concepts apply to most backend technologies.

1. First, why do we need a database connection pool?

Let's start with a basic question.

What happens when an API needs to execute a database query?

At a high level, the application needs a connection to the database, sends a query, receives the result and then releases the connection for reuse.

Opening a brand-new database connection for every request is expensive.

Establishing a connection can involve:

A network connection between the application and database.
Authentication.
Database session initialization.
TLS negotiation, if configured.
Other database and driver-specific setup.

Now imagine an application receiving 500 requests simultaneously.

If every request independently opens a new database connection, we could end up creating hundreds of connections unnecessarily.

That introduces overhead and can overwhelm the database server.

Instead, we use a connection pool.

A connection pool maintains a collection of reusable database connections. When an application needs a connection, it borrows one from the pool. Once the operation is finished, the connection is returned so another operation can use it.

Think of it like a shared collection of resources:

A request needs a database connection.
The pool provides an available connection.
The request executes its database operation.
The connection is released back to the pool.
Another request can reuse it.

The important part is that the application doesn't need to establish a new physical connection for every query.

One important distinction: A connection pool is not the same as a database connection.

The pool manages connections. Your application borrows and returns them as database operations require.

2. How connection pooling works in Go

Go makes connection pooling particularly interesting because database/sql manages the pool for us.

Consider this example:

db, err := sql.Open("postgres", connectionString)
if err != nil {
    log.Fatal(err)
}

defer db.Close()

A common misconception is that sql.Open() immediately establishes a database connection.

It doesn't necessarily do that.

sql.Open() creates a *sql.DB handle, which manages a pool of connections. Actual connections are typically established when they're needed.

If you want to verify that the database is reachable during application startup, use PingContext():

ctx, cancel := context.WithTimeout(
    context.Background(),
    5*time.Second,
)
defer cancel()

if err := db.PingContext(ctx); err != nil {
    log.Fatalf("database connection failed: %v", err)
}

Also, notice something important:

*sql.DB is designed to be long-lived and shared across goroutines.

You generally create one database handle during application startup and reuse it throughout the application's lifetime.

You should not create a new sql.DB inside every API handler.

For example, avoid this:

func GetUsers(w http.ResponseWriter, r *http.Request) {
    db, err := sql.Open("postgres", connectionString)
    if err != nil {
        http.Error(w, "Database error", 500)
        return
    }

    defer db.Close()

    // Execute query...
}

Why?

Because every handler creates its own pool. Instead of sharing a controlled number of connections, you end up with multiple independent pools.

This can cause:

Unnecessary connection creation.
Too many connections on the database server.
More resource consumption.
Difficult-to-manage connection limits.

A better approach is to initialize the pool once and inject the shared *sql.DB into your repository or service layer.

type UserRepository struct {
    db *sql.DB
}

func NewUserRepository(db *sql.DB) *UserRepository {
    return &UserRepository{
        db: db,
    }
}

Now every repository operation uses the same pool.

3. Understanding the connection pool configuration

Go provides several methods to control the pool.

These are worth understanding properly because setting them without understanding their impact can create production issues.

`SetMaxOpenConns`

db.SetMaxOpenConns(25)

This defines the maximum number of open connections that the pool can have at a time.

For example, if the maximum is 25:

Up to 25 connections can be open.
If all 25 are busy, additional operations wait.
When a connection becomes available, a waiting operation can use it.

This is one of the most important settings because it controls how many concurrent database operations can hold connections from that pool.

`SetMaxIdleConns`

db.SetMaxIdleConns(10)

This defines the maximum number of connections that can remain idle in the pool.

Why keep idle connections?

Because creating a new connection takes time. Keeping a reasonable number of connections available can reduce the overhead of establishing new ones.

But don't confuse idle connections with unused resources that are automatically closed immediately. Idle connections can remain open until they are reused or removed by pool lifecycle rules.

`SetConnMaxLifetime`

db.SetConnMaxLifetime(30 * time.Minute)

This sets the maximum amount of time a connection may be reused.

Once a connection reaches its lifetime, it becomes eligible for removal and replacement.

Why is this useful?

Database infrastructure may rotate connections.
Network devices may terminate long-lived connections.
Cloud database environments may have connection lifecycle constraints.
Long-lived sessions can accumulate server-side state.

This does not mean an active query is forcibly interrupted exactly when the lifetime expires. The pool applies connection lifetime rules as connections are returned and reused.

`SetConnMaxIdleTime`

db.SetConnMaxIdleTime(5 * time.Minute)

This controls how long an idle connection can remain unused before it becomes eligible for closure.

For example, imagine your application receives heavy traffic during the day but very little traffic at night.

You might not need to keep every previously opened connection around during idle periods.

This setting helps the pool clean up connections that have been sitting unused.

Putting everything together

A basic configuration might look like this:

func NewDatabase(dsn string) (*sql.DB, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, err
    }

    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(10)
    db.SetConnMaxLifetime(30 * time.Minute)
    db.SetConnMaxIdleTime(5 * time.Minute)

    ctx, cancel := context.WithTimeout(
        context.Background(),
        5*time.Second,
    )
    defer cancel()

    if err := db.PingContext(ctx); err != nil {
        db.Close()
        return nil, err
    }

    return db, nil
}

These values are examples, not universal production defaults. Your actual configuration should depend on database capacity, application concurrency, query behavior, number of instances and workload.

We'll come back to sizing later.

4. The real problem: How does an application run out of connections?

Now let's get to the interesting part.

Suppose your application has the following configuration:

db.SetMaxOpenConns(5)

That means the pool can have at most five open connections.

Imagine five API requests are executing database operations simultaneously.

All five connections are occupied.

Now a sixth request arrives.

What happens?

It waits until one of the existing operations releases a connection.

This is expected behavior.

But what if those five connections are never released?

The sixth request keeps waiting.

The seventh request keeps waiting.

Eventually, requests start timing out and your application appears to be stuck.

This is called connection pool exhaustion.

The database itself might still be healthy. The problem is that your application cannot obtain a connection from its own pool.

Let's look at the most common reasons.

5. Common causes of connection leaks and pool exhaustion

Problem 1: Forgetting to close query rows

This is one of the easiest mistakes to make.

Consider:

func GetUsers(db *sql.DB) error {
    rows, err := db.Query("SELECT id, name FROM users")
    if err != nil {
        return err
    }

    for rows.Next() {
        var id int
        var name string

        if err := rows.Scan(&id, &name); err != nil {
            return err
        }

        fmt.Println(id, name)
    }

    return nil
}

Looks perfectly fine, right?

But there's an issue.

We never close rows.

A Rows object can hold a database connection while the result set is being consumed. If it isn't closed, the connection may remain unavailable to other operations.

A safer implementation:

func GetUsers(db *sql.DB) error {
    rows, err := db.Query("SELECT id, name FROM users")
    if err != nil {
        return err
    }
    defer rows.Close()

    for rows.Next() {
        var id int
        var name string

        if err := rows.Scan(&id, &name); err != nil {
            return err
        }

        fmt.Println(id, name)
    }

    return rows.Err()
}

Three important things are happening here:

defer rows.Close() ensures cleanup when the function returns, including error paths.
rows.Err() checks whether iteration ended because of an error.
The connection can be returned to the pool once the result set is closed and the operation is finished.

A practical rule: Whenever you call Query() and receive *sql.Rows, close it.

Also, remember that QueryRow() behaves differently: it represents a single-row result and doesn't require you to call Close().

Problem 2: Not completing database transactions

Transactions are another common source of connection exhaustion.

Consider:

func UpdateUser(db *sql.DB) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }

    _, err = tx.Exec(
        "UPDATE users SET status = ? WHERE id = ?",
        "active",
        10,
    )

    if err != nil {
        return err
    }

    return nil
}

What's wrong here?

We started a transaction but never committed or rolled it back.

A transaction holds its underlying connection until it is completed.

If this happens repeatedly, connections can remain occupied and the pool can eventually become exhausted.

A safer pattern:

func UpdateUser(db *sql.DB) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }

    defer tx.Rollback()

    _, err = tx.Exec(
        "UPDATE users SET status = ? WHERE id = ?",
        "active",
        10,
    )
    if err != nil {
        return err
    }

    if err := tx.Commit(); err != nil {
        return err
    }

    return nil
}

Why defer Rollback() if we're going to commit?

Because it provides cleanup for every early return.

After a successful commit, the deferred rollback simply returns an error indicating that the transaction has already completed. It's safe to ignore that result in this cleanup pattern.

The important thing is that every transaction should have a clearly defined completion path.

Never start a transaction and leave its lifecycle uncertain.

Problem 3: Starting another database operation inside a transaction

Here's a subtle issue that can be particularly confusing.

Imagine your pool has only one connection:

db.SetMaxOpenConns(1)

Now consider:

func UpdateAndFetch(db *sql.DB) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }
    defer tx.Rollback()

    _, err = tx.Exec(
        "UPDATE users SET status = ? WHERE id = ?",
        "active",
        10,
    )
    if err != nil {
        return err
    }

    var name string

    err = db.QueryRow(
        "SELECT name FROM users WHERE id = ?",
        10,
    ).Scan(&name)

    if err != nil {
        return err
    }

    return tx.Commit()
}

Can you spot the problem?

The transaction already holds the only available connection.

But the next query uses db.QueryRow(), which tries to acquire a connection from the pool.

There are no available connections.

The transaction is waiting for the query to finish and the query is waiting for the transaction's connection to become available.

Neither can proceed.

This is a deadlock-like situation caused by exhausting the pool.

The fix is simple: execute queries that belong to the transaction through tx, not through db.

err = tx.QueryRow(
    "SELECT name FROM users WHERE id = ?",
    10,
).Scan(&name)

This is an especially important distinction:

db.Exec() / db.Query() acquire connections from the pool.
tx.Exec() / tx.Query() use the connection already reserved by that transaction.

Problem 4: Long-running queries

Not every pool exhaustion issue is caused by a connection leak.

Sometimes, connections are being released correctly, but database operations are taking too long.

Imagine:

Your pool has 20 connections.
20 requests execute slow database queries.
Each query takes 15 seconds.
Another 100 requests arrive during that period.

Those new requests must wait for connections.

The application may appear unresponsive even though no connection has leaked.

Common reasons include:

Missing database indexes.
Queries scanning too many rows.
Unnecessary joins.
Lock contention.
Large result sets.
Database CPU or I/O saturation.
Slow network communication.

This is why increasing MaxOpenConns isn't always the solution.

If the database is already struggling, allowing more concurrent queries may make things worse.

The right approach is to investigate query execution time, database load and lock waits.

Problem 5: Queries without timeouts

Consider:

rows, err := db.Query(
    "SELECT id, name FROM users",
)

What happens if the database takes too long to respond?

Without a suitable context deadline, the operation may wait longer than the caller can reasonably tolerate.

Use context-aware operations:

ctx, cancel := context.WithTimeout(
    context.Background(),
    3*time.Second,
)
defer cancel()

rows, err := db.QueryContext(
    ctx,
    "SELECT id, name FROM users",
)
if err != nil {
    return err
}
defer rows.Close()

A context deadline gives the operation a time limit and allows cancellation to propagate through the database driver where supported.

Be careful, though: a timeout is not a substitute for closing rows or completing transactions.

You need both proper resource cleanup and sensible deadlines.

6. Let's reproduce connection pool exhaustion

Theory is useful, but let's actually see what happens.

We'll intentionally create a small pool and hold connections for a few seconds.

package main

import (
    "context"
    "database/sql"
    "fmt"
    "log"
    "time"
)

func main() {
    db, err := sql.Open("postgres", "your-connection-string")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    db.SetMaxOpenConns(2)
    db.SetMaxIdleConns(2)

    for i := 1; i <= 5; i++ {
        go func(id int) {
            ctx, cancel := context.WithTimeout(
                context.Background(),
                10*time.Second,
            )
            defer cancel()

            start := time.Now()

            conn, err := db.Conn(ctx)
            if err != nil {
                fmt.Printf(
                    "Worker %d failed: %v\n",
                    id,
                    err,
                )
                return
            }
            defer conn.Close()

            fmt.Printf(
                "Worker %d acquired connection in %v\n",
                id,
                time.Since(start),
            )

            time.Sleep(5 * time.Second)

            fmt.Printf("Worker %d released connection\n", id)
        }(i)
    }

    time.Sleep(12 * time.Second)

    stats := db.Stats()

    fmt.Printf("Open: %d\n", stats.OpenConnections)
    fmt.Printf("In use: %d\n", stats.InUse)
    fmt.Printf("Idle: %d\n", stats.Idle)
    fmt.Printf("Wait count: %d\n", stats.WaitCount)
    fmt.Printf("Wait duration: %v\n", stats.WaitDuration)
}

Here, we're deliberately limiting the pool to two connections while starting five workers.

What should happen?

The first two workers acquire connections.
The remaining three workers wait.
When one of the first workers closes its connection, a waiting worker can acquire it.
The process continues until all workers finish or their contexts expire.

Notice this line:

defer conn.Close()

It returns the reserved connection to the pool.

For this demonstration, we're using db.Conn() to reserve a connection explicitly. In normal application code, you generally use QueryContext, ExecContext, or a transaction and let database/sql manage connection acquisition.

Try changing the sleep duration, pool size and context timeout. You'll get a much better understanding of how pool contention behaves.

7. How to debug connection pool exhaustion in a real application

Now imagine this happens in production.

The API is slow, requests are timing out and the database pool is fully occupied.

Where do you start?

Don't immediately increase the connection limit or restart the application.

First, collect evidence.

Step 1: Check pool statistics

Go provides a very useful method:

stats := db.Stats()

It returns a DBStats structure containing information about the pool.

Some important fields:

Field	What it tells you
`OpenConnections`	Currently open connections
`InUse`	Connections currently checked out
`Idle`	Connections currently idle
`MaxOpenConnections`	Configured maximum
`WaitCount`	Total number of waits for a connection
`WaitDuration`	Total time spent waiting for connections

Let's log them:

func LogDBStats(db *sql.DB) {
    stats := db.Stats()

    log.Printf(
        "DB Pool | Open: %d | InUse: %d | Idle: %d | MaxOpen: %d | WaitCount: %d | WaitDuration: %v",
        stats.OpenConnections,
        stats.InUse,
        stats.Idle,
        stats.MaxOpenConnections,
        stats.WaitCount,
        stats.WaitDuration,
    )
}

Call this periodically or expose these values through your application's metrics endpoint.

Now imagine you see:

DB Pool | Open: 25 | InUse: 25 | Idle: 0 |
MaxOpen: 25 | WaitCount: 1200 | WaitDuration: 45s

What does this tell us?

All 25 connections are currently occupied.
There are no idle connections available.
Other operations have been waiting for connections.
The pool is experiencing contention.

This is a strong indication that the pool is under pressure.

But don't jump to the conclusion that connections are leaking.

The same pattern can be caused by slow queries, long transactions, high request concurrency, or actual leaks.

Important: WaitCount and WaitDuration are cumulative counters. They aren't necessarily the number of requests waiting right now.

For meaningful monitoring, compare their values over time. For example, calculate the increase in WaitCount and WaitDuration over each monitoring interval.

Step 2: Check whether connections are being released

This is where you investigate the code.

Search for:

db.Query() without rows.Close().
Transactions without a commit or rollback.
Early returns before cleanup.
Long-running queries.
Database operations inside loops.
Connections reserved using db.Conn() without Close().
Rows that remain open while unrelated work is performed.

Pay special attention to functions that execute multiple database operations.

For example:

rows, err := db.QueryContext(ctx, query)
if err != nil {
    return err
}

// Some processing...

if someCondition {
    return nil
}

If rows.Close() is missing, that early return can leave the result set open.

Using defer rows.Close() immediately after successfully acquiring rows is a much safer pattern.

Step 3: Check the database server itself

Your application metrics tell you what is happening inside the pool.

But they don't tell you everything about the database.

You should also investigate the database server.

For PostgreSQL, you can inspect active sessions using:

SELECT
    pid,
    usename,
    state,
    wait_event_type,
    wait_event,
    query_start,
    NOW() - query_start AS query_duration,
    query
FROM pg_stat_activity
WHERE datname = current_database()
ORDER BY query_start;

Look for:

Long-running queries.
Sessions waiting on locks.
Unexpectedly high numbers of active sessions.
Sessions in idle in transaction state.

That last state is particularly interesting.

An idle in transaction session means a transaction has started but is currently not executing a query and has not been completed.

Such transactions can hold locks and other resources and can contribute to connection pressure.

For MySQL, you can inspect current sessions using:

SHOW FULL PROCESSLIST;

Look at the connection count, query duration and session state.

These checks help distinguish application-side connection leaks from database-side performance or locking problems.

Step 4: Check query latency and acquisition time separately

This is a debugging detail worth remembering.

A database operation can be slow for two very different reasons:

It took a long time to acquire a connection.
It acquired a connection quickly, but the query itself took a long time.

These should be measured separately.

For example:

start := time.Now()

rows, err := db.QueryContext(ctx, query)
acquireAndExecuteDuration := time.Since(start)

if err != nil {
    return err
}
defer rows.Close()

log.Printf(
    "Query call duration: %v",
    acquireAndExecuteDuration,
)

This measures the time spent obtaining a connection and executing the query call until it returns its rows. It is not necessarily the full time spent consuming the result set.

For more detailed observability, instrument:

Connection acquisition duration.
Query execution duration.
Rows iteration duration.
Transaction duration.
Connection pool wait statistics.

This makes it much easier to identify where the time is actually going.

Step 5: Don't use application restarts as the permanent fix

Restarting an application can temporarily solve a pool exhaustion issue because closing the database handle releases its connections.

But if the underlying bug remains, it will happen again.

A restart is a recovery action, not a root-cause fix.

The goal should be to identify why connections are staying occupied and correct that behavior.

8. How should you choose the connection pool size?

This is one of the most common configuration questions.

Should MaxOpenConns be 10, 25, 50, or 100?

There is no universal answer.

It depends on your workload and database capacity.

Let's take an example.

Suppose your database server allows 200 connections.

Your architecture has:

3 application instances.
1 background worker service.
1 scheduled job service.
Database administration and migration connections.

If every application instance configures:

db.SetMaxOpenConns(100)

Then your three application instances alone could potentially open 300 connections.

That's already more than the database's total connection limit.

Remember:

The connection limit applies to the database server, not just one application instance.

A better way to think about it:

Database connection budget
    |
    +-- Application instance 1
    +-- Application instance 2
    +-- Application instance 3
    +-- Background workers
    +-- Scheduled jobs
    +-- Migrations and administration
    +-- Operational reserve

The total possible connections across all these consumers must fit within the database's available capacity.

You should also leave room for database maintenance and other operational needs.

What factors should influence the pool size?

1. Number of application instances

A pool size of 25 across four instances can potentially mean 100 connections.

2. Query execution time

Long-running queries occupy connections longer, increasing contention.

3. Request concurrency

A large number of concurrent requests doesn't automatically mean you need an equally large database pool. Many requests may not need the database simultaneously.

4. Database capacity

The database must be able to handle the number of concurrent queries efficiently.

5. Background jobs

Workers and scheduled tasks also consume connections and must be included in your calculations.

6. Connection limits of your database infrastructure

Managed databases, self-hosted databases and connection proxies may impose different limits.

A practical approach

Start with a conservative pool size.

Then:

Load test realistic traffic.
Monitor InUse, Idle, WaitCount and WaitDuration.
Check query latency and database CPU.
Identify whether connection waits are caused by slow queries or insufficient pool capacity.
Increase the limit gradually if the database has capacity.
Repeat the load test and compare results.

Don't increase the pool size simply because requests are waiting.

More connections can increase database contention and make the situation worse.

The objective isn't to maximize the number of connections.

It's to find a balance between application concurrency and database capacity.

9. Best practices for production applications

Let's put the important practices together.

1. Create one shared database pool

Initialize *sql.DB during application startup and reuse it.

Avoid creating a new pool for every request or repository operation.

2. Always close query rows

rows, err := db.QueryContext(ctx, query)
if err != nil {
    return err
}
defer rows.Close()

Do this immediately after successfully obtaining rows.

3. Always complete transactions

Use a clear commit or rollback path.

A deferred rollback is a useful safety net for early returns.

4. Use context-aware database operations

Prefer:

db.QueryContext(ctx, query)
db.ExecContext(ctx, query)
db.BeginTx(ctx, nil)

Use sensible deadlines based on the operation and API requirements.

5. Don't hold connections longer than necessary

Avoid performing unrelated work while holding:

Open result sets.
Transactions.
Reserved connections.

For example, don't make an external HTTP request while holding a database transaction unless that is an intentional and carefully designed requirement.

6. Monitor pool statistics

Expose connection pool metrics and alert on sustained saturation, increasing wait time and unusual connection usage.

7. Monitor the database too

Application metrics alone aren't enough.

Track database CPU, memory, query latency, locks, active sessions and connection usage.

8. Size pools across all application instances

Don't configure every instance independently without considering the total database connection budget.

9. Use query timeouts and appropriate indexes

A slow query can occupy a connection just as effectively as a leaked connection.

Optimize the query instead of blindly increasing the pool.

10. Test under concurrency

A database operation that works perfectly in a single-request test may behave very differently under concurrent load.

Load testing and integration testing can expose resource lifecycle problems before production does.

10. A few misconceptions worth clearing up

Misconception 1: Increasing MaxOpenConns always fixes connection exhaustion.

Not true. If connections are leaking or queries are too slow, increasing the limit may only delay the problem or overload the database.

Misconception 2: sql.Open() immediately creates a database connection.

Not necessarily. It creates a pool handle. Use PingContext() when you need to verify connectivity.

Misconception 3: Idle connections are bad.

Not necessarily. Idle connections are reusable resources. The problem is keeping more of them than your workload or infrastructure needs.

Misconception 4: Every connection leak is caused by forgetting rows.Close().

No. Unfinished transactions, reserved connections that aren't closed, slow operations and other resource-lifecycle issues can also cause pool exhaustion.

Misconception 5: A healthy database means the application can always query it.

Not true. Your application's local connection pool can be exhausted even when the database server itself is healthy.

Misconception 6: MaxOpenConns should match the number of API requests.

No. Many API requests don't execute database queries simultaneously. Pool sizing should be based on actual database concurrency and server capacity.

11. Your production debugging checklist

If your application suddenly starts timing out while communicating with the database, here's a practical checklist to follow.

[ ] Check whether InUse has reached MaxOpenConnections.
[ ] Check whether Idle is consistently zero.
[ ] Compare WaitCount and WaitDuration over time.
[ ] Check for missing rows.Close() calls.
[ ] Check whether transactions are always committed or rolled back.
[ ] Look for reserved connections that aren't closed.
[ ] Identify long-running queries.
[ ] Inspect database locks and idle in transaction sessions.
[ ] Separate connection acquisition time from query execution time.
[ ] Check total connections across all application instances.
[ ] Review context deadlines and query timeouts.
[ ] Load test the fix before deploying it.

This checklist won't automatically identify every possible issue, but it gives you a systematic place to start instead of randomly changing pool configuration.

Final thoughts

Database connection pooling is not just about setting MaxOpenConns and MaxIdleConns and moving on.

It's about understanding how your application acquires, uses and releases database connections.

A missing rows.Close(), an unfinished transaction, or a query that takes much longer than expected can occupy connections and eventually prevent the rest of your application from accessing the database.

The interesting part is that the database might be completely healthy while your application is unable to execute another query.

That's why connection pool monitoring, proper resource cleanup, query optimization and realistic pool sizing are all important parts of building reliable backend systems.

If there's one thing I'd like you to take away from this article, it's this:

Don't just monitor whether your database is up. Monitor whether your application can actually get a connection to use it.

Because sometimes, the problem isn't that your database stopped working. It's that your application ran out of ways to talk to it.

💬 Have you ever debugged a connection pool exhaustion issue in a production application?

What was the actual root cause - a connection leak, a long-running query, an unfinished transaction, or something else?

I'd love to hear about real-world debugging experiences in the comments.

Happy debugging! 🚀

🧩 JavaScript Promises Inside Promises: The Hidden Bugs, Execution Flow and How to Fix Them

Fazal Mansuri — Fri, 02 Oct 2026 13:10:36 +0000

Have you ever debugged JavaScript code where a function says “Done!”, but the operation it depends on is still running?

Or perhaps an API request fails, but the error never reaches the catch() block you expected to handle it.

You inspect the code. You see .then(), another .then(), maybe a new Promise() inside another Promise and suddenly the execution flow becomes difficult to follow.

Sound familiar?

As JavaScript developers, we use Promises for API calls, database operations, file processing, authentication, background tasks and countless other asynchronous operations. Yet some of the bugs we encounter aren't caused by Promises themselves. They're caused by how we connect them.

Consider this example:

fetchUser()
  .then((user) => {
    saveUser(user);
  })
  .then(() => {
    console.log("User saved successfully!");
  });

Looks reasonable, right?

But what if saveUser() returns a Promise?

The success message can appear before the save operation finishes. Worse, if saving fails, the error might not reach the error handler you intended to use.

The problem isn't that Promises are outdated or that nested Promises are always bad. The problem is understanding which asynchronous operation the current chain is actually waiting for.

In this article, we'll work through these issues step by step:

What really happens when a Promise is created inside another Promise?
How does JavaScript execute synchronous code, Promise callbacks and timers?
Why does forgetting return break a Promise chain?
How do nested Promises differ from normal Promise chaining?
Does the same bug happen with async/await?
When should you use Promises, async/await, Promise.all(), or a background task?
How can you debug these problems in a real application?

Let's start with a bug we can reproduce.

1. First, let's reproduce the bug

Imagine you're building a user registration API.

After a user registers, your application needs to:

Save the user's information.
Send a welcome email.
Confirm that registration has completed.

For simplicity, we'll simulate the database and email operations using Promises.

The buggy implementation

function saveUser() {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log("1. User saved to database");
      resolve({ id: 101, name: "Fazal" });
    }, 1000);
  });
}

function sendWelcomeEmail(user) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`2. Welcome email sent to ${user.name}`);
      resolve();
    }, 2000);
  });
}

function registerUser() {
  return saveUser()
    .then((user) => {
      sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

registerUser();

What do you expect to happen?

A reasonable expectation is:

1. User saved to database
2. Welcome email sent to Fazal
3. Registration completed successfully

But the actual output is:

1. User saved to database
3. Registration completed successfully
2. Welcome email sent to Fazal

Wait. Why?

We called sendWelcomeEmail(user) before logging the success message. Shouldn't JavaScript wait for it?

No. Calling an asynchronous function that returns a Promise does not automatically make the surrounding code wait for that Promise.

Let's understand exactly where the execution flow goes wrong.

What JavaScript actually does

Look at this callback:

.then((user) => {
  sendWelcomeEmail(user);
})

The function calls sendWelcomeEmail(user), which starts the email operation and returns a Promise.

But the callback doesn't return that Promise.

From the Promise chain's perspective, this callback returns undefined.

That means the next .then() doesn't need to wait for the email operation.

saveUser()
    |
    | Promise fulfills
    v
First .then()
    |
    | Starts email operation
    | Does NOT return its Promise
    v
First .then() fulfills with undefined
    |
    v
Second .then()
    |
    | Runs immediately after the previous
    | Promise reaction completes
    v
"Registration completed successfully"
    |
    | Email operation is still running
    v
"Welcome email sent to Fazal"

The exact wording matters here: the next .then() doesn't run synchronously inside the previous callback. It runs as a Promise reaction after the preceding chain Promise fulfills. But because the preceding callback returned undefined, that fulfillment doesn't depend on the email Promise.

This is the central bug.

The fix: return the Promise

function registerUser() {
  return saveUser()
    .then((user) => {
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

Now the output is:

1. User saved to database
2. Welcome email sent to Fazal
3. Registration completed successfully

We changed only one thing: we returned the inner Promise.

JavaScript can now connect the two asynchronous operations into one chain.

A shorter version works too:

function registerUser() {
  return saveUser()
    .then((user) => sendWelcomeEmail(user))
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

When an arrow function has an expression body, that expression is returned implicitly. Here, the expression is the Promise returned by sendWelcomeEmail().

Keep this rule in mind throughout the article:

If the next step must wait for an asynchronous operation, make sure that operation's Promise is returned or awaited.

But why does returning a Promise work? To understand that, we need to look at how Promises actually behave.

2. What is a Promise, really?

A Promise represents the eventual outcome of an asynchronous operation.

It can be in one of three states:

Pending: The operation hasn't settled yet.
Fulfilled: The operation completed successfully.
Rejected: The operation failed.

A Promise that has fulfilled or rejected is called settled.

For example:

const result = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("Data loaded");
  }, 1000);
});

result.then((value) => {
  console.log(value);
});

Output after approximately one second:

Data loaded

The Promise starts pending. After the timer callback runs, it fulfills with "Data loaded".

The .then() callback runs as a Promise reaction, rather than being invoked immediately by the call to resolve().

One important distinction: a Promise doesn't make an operation asynchronous by itself. The operation may involve a timer, network request, or other asynchronous API. A Promise provides a way to represent and compose its outcome.

Also, the Promise executor—the function passed to new Promise()—runs synchronously.

Let's verify that.

console.log("1. Before");

const promise = new Promise((resolve) => {
  console.log("2. Inside executor");
  resolve("Done");
});

promise.then((value) => {
  console.log("4.", value);
});

console.log("3. After");

Output:

1. Before
2. Inside executor
3. After
4. Done

Why?

JavaScript logs "Before".
The Promise constructor immediately invokes its executor, so "Inside executor" appears next.
resolve("Done") fulfills the Promise, but its .then() reaction doesn't run inline.
JavaScript continues with the remaining synchronous code.
The Promise reaction runs as a microtask.

This distinction becomes important when you see a Promise inside another Promise.

3. What happens when a Promise is inside another Promise?

There are two patterns that developers often confuse.

Pattern A: Returning a Promise from another Promise

const outerPromise = new Promise((resolve) => {
  resolve(
    new Promise((innerResolve) => {
      setTimeout(() => {
        innerResolve("Inner operation completed");
      }, 1000);
    })
  );
});

outerPromise.then((result) => {
  console.log(result);
});

Output after approximately one second:

Inner operation completed

Notice something important: outerPromise doesn't fulfill with the inner Promise object as its final value.

When a Promise is resolved with another Promise, it adopts the inner Promise's eventual state and outcome.

In this example:

The outer Promise's executor starts synchronously.
The inner Promise is created and its executor also starts synchronously.
resolve(innerPromise) resolves the outer Promise to follow the inner Promise.
The timer eventually fulfills the inner Promise.
The outer Promise then fulfills with "Inner operation completed".
The outer Promise's .then() reaction receives that string.

Conceptually:

Outer Promise
     |
     | resolved with inner Promise
     v
Inner Promise
     |
     | pending for 1 second
     v
Fulfilled with a string
     |
     v
Outer Promise fulfills with the same outcome
     |
     v
.then() receives the string

This behavior is part of Promise resolution. It's why Promise chains can be composed without manually inspecting whether each returned value is itself a Promise.

Pattern B: Creating a Promise but not returning it

Now compare that with:

const outerPromise = new Promise((resolve) => {
  new Promise((innerResolve) => {
    setTimeout(() => {
      innerResolve("Inner operation completed");
    }, 1000);
  });

  resolve("Outer operation completed");
});

outerPromise.then((result) => {
  console.log(result);
});

Output:

Outer operation completed

The inner Promise still runs. After approximately one second, it fulfills with "Inner operation completed", but nothing consumes that result.

The outer Promise doesn't wait for it because the inner Promise was neither returned from a relevant callback nor used to resolve the outer Promise.

This is a subtle but important distinction:

Creating a Promise starts the executor and establishes an asynchronous result.
Returning a Promise from a .then() callback connects its outcome to the chain.
Resolving a Promise with another Promise makes the first Promise adopt the second Promise's outcome.

These are related concepts, but they aren't interchangeable.

A complete execution-order example

Let's combine synchronous execution, nested Promise creation, a timer and .then().

console.log("0. Start");

function getUser() {
  return new Promise((resolve) => {
    console.log("1. Outer executor");

    resolve(
      new Promise((innerResolve) => {
        console.log("2. Inner executor");

        setTimeout(() => {
          console.log("4. Inner timer");
          innerResolve({ id: 1, name: "Fazal" });
        }, 1000);
      })
    );
  });
}

getUser().then((user) => {
  console.log("5. User:", user.name);
});

console.log("3. End");

Output:

0. Start
1. Outer executor
2. Inner executor
3. End
4. Inner timer
5. User: Fazal

The two executor messages appear immediately because both executors run synchronously. The "End" message follows because JavaScript continues running synchronous code. The timer callback executes later and the .then() callback runs after the Promise has fulfilled.

You don't need to memorize this particular output. You need to understand which operations are synchronous, which callbacks are scheduled and which Promise outcomes are connected.

4. Nested `.then()` callbacks vs. Promise chaining

Let's return to the registration example.

A nested version might look like this:

function registerUser() {
  return saveUser().then((user) => {
    return sendWelcomeEmail(user).then(() => {
      console.log("Email step completed");
      return user;
    });
  });
}

registerUser().then((user) => {
  console.log("Registration flow completed for", user.name);
});

This is valid JavaScript. The inner .then() returns a Promise and the outer callback returns that Promise. The whole chain waits for the email operation.

But nesting adds indentation and makes longer flows harder to follow.

We can express the same dependency using a flat chain:

function registerUser() {
  let registeredUser;

  return saveUser()
    .then((user) => {
      registeredUser = user;
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("Email step completed");
      return registeredUser;
    });
}

registerUser().then((user) => {
  console.log("Registration flow completed for", user.name);
});

Both versions wait for the email operation.

The flat chain makes the sequence easier to scan, although it uses a variable to preserve the user value. In production, you should consider whether that extra state is necessary and whether it makes the flow clearer.

You can also preserve the user value without an outer variable:

function registerUser() {
  return saveUser().then((user) => {
    return sendWelcomeEmail(user).then(() => user);
  });
}

Or, using async/await:

async function registerUser() {
  const user = await saveUser();
  await sendWelcomeEmail(user);
  return user;
}

There isn't a universal rule that every nested .then() is wrong. Nesting is sometimes natural when a local operation has its own result handling. The problem is accidental nesting that hides dependencies, loses return values, or makes error handling confusing.

5. The missing `return`: a small mistake with several consequences

Let's examine the most common version of this bug more closely.

Case 1: The next step starts too early

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      updateOrderStatus(order.id, payment);
    })
    .then(() => {
      console.log("Order processing completed");
    });
}

If updateOrderStatus() returns a Promise, the final callback doesn't wait for it.

Correct version:

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      return updateOrderStatus(order.id, payment);
    })
    .then(() => {
      console.log("Order processing completed");
    });
}

Now the next step waits for the status update.

Case 2: Errors don't propagate through the expected chain

Suppose an inner operation rejects.

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      updateOrderStatus(order.id, payment);
    })
    .catch((error) => {
      console.error("Order processing failed:", error);
    });
}

If updateOrderStatus() returns a Promise that rejects, the .catch() above won't catch that rejection through this chain because its Promise was never returned.

Correct version:

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      return updateOrderStatus(order.id, payment);
    })
    .catch((error) => {
      console.error("Order processing failed:", error);
      throw error;
    });
}

Notice the throw error.

Without it, the .catch() callback would fulfill the chain with undefined if it simply logged the error and returned nothing. Downstream code could then mistake the failure for success.

You should decide whether to rethrow, recover with a fallback, or handle the error and intentionally return a successful result. The right choice depends on the application.

Case 3: The caller receives a result too early

Imagine a function that should return the saved record:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    refreshSearchIndex(savedProfile);
  });
}

The caller receives a Promise that fulfills with undefined after the callback finishes—not with the search-index operation's result.

If the caller expects to wait for indexing too, return its Promise:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    return refreshSearchIndex(savedProfile);
  });
}

If the caller needs the saved profile as its result after indexing finishes:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    return refreshSearchIndex(savedProfile).then(() => savedProfile);
  });
}

This makes the intended result explicit.

Important: Don't return a Promise just to make every operation sequential. Return it when the caller needs to wait for that operation or depend on its outcome. Independent work may be better handled concurrently or in the background.

6. Is this bug specific to Promises, or does it also happen with `async/await`?

This is an excellent question because async/await often makes asynchronous code easier to read, but it doesn't eliminate the underlying problem.

The bug is generic to asynchronous control flow. It happens whenever the program starts work but fails to connect that work to the sequence that depends on it.

Let's translate the registration example.

Incorrect `async/await` implementation

async function registerUser() {
  const user = await saveUser();

  sendWelcomeEmail(user);

  console.log("Registration completed successfully");
}

registerUser();

The output can still be:

1. User saved to database
3. Registration completed successfully
2. Welcome email sent to Fazal

Why?

Because sendWelcomeEmail(user) starts the operation, but the function doesn't await its Promise.

The async keyword does not automatically wait for every Promise created inside the function.

Correct implementation

async function registerUser() {
  const user = await saveUser();

  await sendWelcomeEmail(user);

  console.log("Registration completed successfully");
}

registerUser();

Now the function waits for the email operation before logging success.

The difference is not that async/await has magical asynchronous behavior. It provides syntax for expressing the dependency clearly.

Compare the two patterns:

// Promise chaining
return saveUser()
  .then((user) => sendWelcomeEmail(user))
  .then(() => {
    console.log("Registration completed");
  });

// async/await
async function registerUser() {
  const user = await saveUser();
  await sendWelcomeEmail(user);

  console.log("Registration completed");
}

Both can represent the same sequence of operations.

A useful rule

If a later step must wait for an asynchronous operation:

With Promise chaining, return the Promise from the callback.
With async/await, await the Promise.

The underlying principle is the same: explicitly connect the operation to the control flow that depends on it.

7. Error handling: `.catch()` vs. `try/catch`

Correct sequencing is only half the story. We also need to understand how failures propagate.

Promise-based error handling

function registerUser() {
  return saveUser()
    .then((user) => {
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("Registration completed");
    })
    .catch((error) => {
      console.error("Registration failed:", error);
      throw error;
    });
}

A rejection from saveUser() or sendWelcomeEmail() can propagate to the final .catch() because each operation is connected to the chain.

If the email operation rejects, the success callback is skipped and the error handler runs.

The equivalent `async/await` approach

async function registerUser() {
  try {
    const user = await saveUser();
    await sendWelcomeEmail(user);

    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

The try/catch handles rejections from the awaited operations.

However, consider this:

async function registerUser() {
  try {
    const user = await saveUser();

    sendWelcomeEmail(user);
    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

If sendWelcomeEmail() returns a Promise that rejects, this catch won't catch that rejection through the try block because the Promise wasn't awaited. It may instead become an unhandled rejection, depending on what else handles it.

Correct:

async function registerUser() {
  try {
    const user = await saveUser();

    await sendWelcomeEmail(user);

    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

There is one additional nuance: try/catch catches synchronous exceptions thrown while executing the try block, as well as rejections from awaited Promises. It doesn't automatically catch failures from unrelated asynchronous operations that you start and leave unawaited.

That is why await matters for error handling as well as sequencing.

Should you always rethrow an error?

No.

Rethrow when the caller needs to know the operation failed. Recover when you have a meaningful fallback. Handle the error without rethrowing only when the function's contract says the failure has been dealt with and downstream code should continue.

For example, an optional analytics event might fail without preventing an order from being completed. A payment failure should not be silently swallowed.

Error handling should reflect the business requirement, not just the syntax.

8. Promise vs. `async/await`: which should you use?

This isn't a competition in which one syntax is always correct. async/await is built on Promises and is often easier to read for sequential workflows, while Promise methods remain valuable for composition and concurrency.

Here's a practical comparison.

Scenario A: Sequential operations

Suppose you need to fetch a user, then fetch that user's orders.

Promise chaining:

function getUserOrders(userId) {
  return fetchUser(userId)
    .then((user) => fetchOrders(user.id));
}

Using async/await:

async function getUserOrders(userId) {
  const user = await fetchUser(userId);
  const orders = await fetchOrders(user.id);

  return orders;
}

Both are valid. The second version can be easier to follow when the workflow contains many steps, conditions, or intermediate variables.

Scenario B: Several independent operations

Suppose a dashboard needs user information, notifications and recommendations. None depends on the others.

This version unnecessarily runs the operations sequentially:

async function loadDashboard() {
  const user = await fetchUser();
  const notifications = await fetchNotifications();
  const recommendations = await fetchRecommendations();

  return { user, notifications, recommendations };
}

If each operation takes time, the total duration can approach the sum of their durations.

Instead, start the independent operations together:

async function loadDashboard() {
  const [user, notifications, recommendations] =
    await Promise.all([
      fetchUser(),
      fetchNotifications(),
      fetchRecommendations()
    ]);

  return { user, notifications, recommendations };
}

Promise.all() fulfills when all supplied Promises fulfill. If one rejects, the returned Promise rejects with that failure, though the other operations aren't automatically cancelled and may continue running.

This is a common example of using async/await and Promise composition together. You don't need to choose one or the other.

Scenario C: Independent operations where partial results matter

Suppose you're loading data from five optional integrations. One failing shouldn't prevent you from displaying the successful results.

Use Promise.allSettled():

async function loadIntegrations() {
  const results = await Promise.allSettled([
    fetchCalendar(),
    fetchTasks(),
    fetchNotifications()
  ]);

  for (const result of results) {
    if (result.status === "fulfilled") {
      console.log("Loaded:", result.value);
    } else {
      console.error("Integration failed:", result.reason);
    }
  }

  return results;
}

This waits for every supplied Promise to settle and gives you the outcome of each one.

Scenario D: You want a Promise chain without an `async` function

Sometimes a small function can be expressed naturally as a chain:

function getDisplayName(userId) {
  return fetchUser(userId)
    .then((user) => user.name)
    .catch((error) => {
      console.error("Unable to load user:", error);
      throw error;
    });
}

You don't have to introduce async/await just because it exists. Promise chaining is still useful, particularly when transforming results or composing functions.

A practical decision guide

Situation	A useful approach
Several dependent steps	`async/await` or a returned Promise chain
Several independent operations	`Promise.all()` with `async/await`
Need the outcome of every operation	`Promise.allSettled()`
Simple result transformation	Promise chaining
Complex branching and intermediate values	Often `async/await`
Background work that shouldn't block the caller	Explicit background-task handling
Need to handle each operation's failure separately	Local `try/catch` or per-Promise `.catch()`

These are guidelines, not strict rules. Readability, error-handling requirements, cancellation needs and the behavior expected by the caller all matter.

9. One real-world decision: should the email block registration?

Our registration example assumes that registration isn't complete until the email has been sent.

But is that always the correct design?

Imagine the database save succeeds and the email provider takes five seconds to respond. Should the user wait five seconds before receiving a successful registration response?

Not necessarily.

This is where we must distinguish a JavaScript bug from a product or architecture decision.

Option A: Email is part of the required workflow

If the operation must finish before the caller can proceed, return or await the email Promise.

async function registerUser(input) {
  const user = await saveUser(input);
  await sendWelcomeEmail(user);

  return user;
}

The caller receives the user only after the awaited email operation fulfills. If it rejects, the function rejects unless the error is handled.

Option B: Registration should succeed independently of email delivery

If the user should be registered even when the email provider is temporarily unavailable, don't pretend that the email is part of the same success condition.

A simple illustrative approach is:

async function registerUser(input) {
  const user = await saveUser(input);

  try {
    await sendWelcomeEmail(user);
  } catch (error) {
    console.error("Welcome email failed:", error);
    // Record or schedule a retry if the application supports it.
  }

  return user;
}

This waits for the email attempt but doesn't let its failure reject registration. It is not truly non-blocking, though, because the function still waits for the attempt to settle.

If email delivery should happen independently, a background job or durable queue is usually more appropriate:

Registration request
       |
       v
Save user + record email job
       |
       v
Return registration result
       |
       v
Background worker
       |
       v
Send email and retry if needed

In a production system, you would need to consider how the job is persisted, retried and monitored. A simple fire-and-forget call such as sendWelcomeEmail(user) is not a reliable substitute for a durable background-work mechanism.

This illustrates an important lesson: waiting for an operation, handling its failure and deciding whether it belongs in the critical path are three separate decisions.

10. How to debug confusing Promise execution flow

When asynchronous code behaves unexpectedly, don't start by rewriting everything with async/await. First establish which Promise represents which operation.

Here is a practical checklist.

Step 1: Add logs at the boundaries

function updateProfile(profile) {
  console.log("Starting update");

  return saveProfile(profile).then((savedProfile) => {
    console.log("Profile saved");

    return refreshSearchIndex(savedProfile);
  }).then(() => {
    console.log("Index refreshed");
  });
}

Log before and after each important operation. This helps you see whether the unexpected order is caused by missing Promise composition or by the operation itself.

Step 2: Inspect every asynchronous callback

For every .then() callback, ask:

Does this callback start another asynchronous operation?
Does the next step need to wait for it?
If yes, am I returning its Promise?
Does this callback need to preserve a value for a later step?

For every async function, ask:

Is the relevant operation awaited?
Does the function return the value the caller expects?
Is the rejection handled at the correct level?

Step 3: Inspect the returned value

A callback with braces doesn't implicitly return its contents:

.then((result) => {
  transformResult(result);
})

This callback returns undefined unless it explicitly returns something.

Compare:

.then((result) => {
  return transformResult(result);
})

And:

.then((result) => transformResult(result))

The latter two return the result of transformResult(), including its Promise if it returns one.

Step 4: Check rejection paths, not just successful execution

A chain may appear correct when every operation succeeds but fail when one rejects.

Test:

The first operation rejects.
An inner asynchronous operation rejects.
A callback throws synchronously.
A fallback handles an error.
A caller expects a result but receives undefined.

A successful manual test alone isn't enough to establish correct error propagation.

Step 5: Write down the intended dependency

Before changing code, express the desired workflow:

Save user
   ↓ must finish before
Send email
   ↓ must finish before
Return success

If the actual requirement is different, draw that flow instead. This helps distinguish a missing return or await from an incorrect assumption about which operations must be sequential.

11. Common misconceptions worth remembering

Misconception 1: Every Promise runs asynchronously.

The executor passed to new Promise() runs synchronously. Promise reactions, such as .then() callbacks, run asynchronously.

Misconception 2: Creating a Promise means the current function waits for it.

It doesn't. You must connect its outcome to the relevant Promise chain or await it.

Misconception 3: async automatically waits for all Promises inside a function.

It doesn't. async makes the function return a Promise. Individual asynchronous operations still need to be awaited or explicitly composed when their completion matters.

Misconception 4: Nested Promises are always bad code.

Not true. Resolving a Promise with another Promise and returning Promises from callbacks are normal parts of Promise composition. Deeply nested callbacks may hurt readability, but nesting itself isn't proof of a bug.

Misconception 5: Promise.all() cancels the other operations when one rejects.

It doesn't automatically cancel them. Its returned Promise rejects when one of its inputs rejects, but the remaining operations may continue.

Misconception 6: Converting everything to async/await fixes asynchronous bugs.

It can improve readability, but forgetting await creates the same fundamental problem as forgetting to return a Promise from a chain.

12. A final debugging challenge

Before finishing, predict the output of this example:

console.log("A");

Promise.resolve()
  .then(() => {
    console.log("B");

    Promise.resolve().then(() => {
      console.log("C");
    });
  })
  .then(() => {
    console.log("D");
  });

console.log("E");

What order do you expect?

The correct output is:

A
E
B
C
D

Here's why:

A runs synchronously.
The first .then() callback is scheduled as a Promise reaction.
E runs before Promise reactions are processed.
The first callback runs and logs B. It creates another Promise reaction but doesn't return that inner Promise.
The inner reaction logs C.
The next callback in the outer chain logs D after the first callback's returned value—undefined—fulfills the preceding chain Promise.

This example shows why you can't simply assume that all nested Promise callbacks execute before the next step in the outer chain. Their scheduling and Promise dependencies both matter.

Try modifying the example to return the inner Promise:

console.log("A");

Promise.resolve()
  .then(() => {
    console.log("B");

    return Promise.resolve().then(() => {
      console.log("C");
    });
  })
  .then(() => {
    console.log("D");
  });

console.log("E");

The output is still:

A
E
B
C
D

The visible output happens to be the same in this example, but the Promise dependency is different. With the return, the outer chain explicitly waits for the inner Promise. Without it, the two branches are not connected, even though this particular output order looks identical.

That's an important debugging lesson: a log sequence alone doesn't always prove that asynchronous operations are correctly connected. Test the behavior and rejection paths, not just the happy-path output.

Conclusion

Promises aren't inherently complicated, but their behavior becomes much easier to understand once you distinguish creating an operation from connecting its outcome to the rest of your code.

If you take only a few lessons from this article, remember these:

Return a Promise from a .then() callback when the chain must wait for that operation.
Await a Promise inside an async function when subsequent code depends on its outcome.
Propagate or handle errors intentionally instead of accidentally converting failures into successful results.
Use Promise.all() for independent operations that can run concurrently and choose Promise.allSettled() when you need every operation's outcome.
Don't assume every asynchronous task should block the caller. Decide whether it belongs in the critical path or should be handled by a background-work mechanism.
Debug the dependency between operations, not just the order of console messages.

And remember: the same control-flow bug can appear with Promise chains and async/await. Changing syntax can make code easier to read, but it doesn't replace understanding the behavior you need.

The next time your application logs “Done” before the work is actually done, look for the missing return, the missing await, or an operation that was never connected to the flow in the first place.

That's often where the real bug begins.

💬 Your turn: Have you ever encountered a missing return or await that caused a race condition or made an error disappear? Share the scenario in the comments. Real debugging experiences are often the best way for all of us to learn.

🧠 AI Context Engineering (Part 5): Context Optimization - Give AI What It Needs, Not Everything You Have

Fazal Mansuri — Sun, 06 Sep 2026 10:51:31 +0000

We've come a long way in this series.

In Part 1, we introduced Context Engineering and why it goes beyond writing better prompts.

In Part 2, we explored tokens, context windows and memory.

In Part 3, we looked at how AI applications get information through RAG, Tool Calling and MCP.

And in Part 4, we explored how AI agents use context and tools to execute multi-step tasks.

Now there's a problem.

A problem that becomes increasingly important as your AI application becomes more capable.

Imagine an agent working on a task for 30 minutes.

During that time, it:

Reads 20 files.
Calls 15 tools.
Retrieves dozens of documents.
Receives thousands of lines of tool output.
Makes several decisions.
Encounters and resolves errors.
Maintains conversation history.

Eventually, you could end up with something like:

System instructions
        +
Conversation history
        +
Tool definitions
        +
Retrieved documents
        +
Tool results
        +
Agent state
        +
Memory
        +
Current request
        ↓
      LLM

You might think:

"Great. The model has everything it needs."

But there's a catch.

Having everything doesn't necessarily mean having the right context.

And that's what Part 5 is about.

🎯 The Real Goal of Context Engineering

The goal isn't:

❌ Put as much information as possible into the context window.

It's:

✅ Build the smallest useful set of information required for the model to make the current decision correctly.

Think of context as a limited working budget.

You have a task.

You have a certain amount of useful information.

Your job is to decide:

What should stay?
What should go?
What should be summarized?
What should be retrieved later?
What should be cached?
What should never enter the context?

That's Context Engineering.

🚨 More Context Can Become a Problem

Consider this request:

"Why is the payment service returning 500?"

Suppose your system retrieves:

✓ Payment service logs
✓ Recent deployment
✓ Database errors
✓ Relevant code
✓ Configuration
✓ Recent incidents
✓ Unrelated authentication logs
✓ Old deployment logs
✓ 500 pages of documentation
✓ 20 previous conversations

Technically, the model has more information.

But did we improve the context?

Not necessarily.

We introduced:

More tokens
More latency
More cost
More irrelevant information
More opportunities for conflicting information

The useful information can become harder to distinguish from everything else.

This is why:

Context quality matters more than context quantity.

Recent production guidance and research on context management similarly emphasize that long agent trajectories can accumulate irrelevant history and tool output, making selection and compression important engineering problems.

🧩 Five Ways to Optimize Context

A practical context pipeline usually has several levers:

                 Information
                     │
                     ▼
               ┌───────────┐
               │  Select   │
               └─────┬─────┘
                     │
                     ▼
               ┌───────────┐
               │ Retrieve  │
               └─────┬─────┘
                     │
                     ▼
               ┌───────────┐
               │ Compress  │
               └─────┬─────┘
                     │
                     ▼
               ┌───────────┐
               │  Cache    │
               └─────┬─────┘
                     │
                     ▼
               ┌───────────┐
               │   LLM     │
               └───────────┘

Let's understand each one.

1️⃣ Selection — Don't Send What You Don't Need

The cheapest token is often the token you never send.

Suppose an AI coding assistant is debugging:

payment-service

Does it need the entire repository?

Probably not.

It might only need:

payment/
 ├── handler.go
 ├── service.go
 ├── payment.go
 └── payment_test.go

Instead of:

Entire Repository
        ↓
      LLM

Use:

User Question
      ↓
Identify Relevant Files
      ↓
Only Relevant Files
      ↓
LLM

This is context selection.

And it can happen before compression.

Why compress information that shouldn't have been included in the first place?

💡 A Simple Rule

Before adding something to context, ask:

"Does the model need this information to make the current decision?"

If the answer is no, don't send it.

This sounds obvious.

But it's one of the easiest things to get wrong in real systems.

2️⃣ Retrieval — Fetch Information Just in Time

Part 3 introduced RAG.

Now we can look at RAG from a different perspective.

Instead of loading everything upfront:

User Request
      ↓
Load 1,000 Documents
      ↓
LLM

retrieve information when it is actually relevant:

User Request
      ↓
Understand Need
      ↓
Retrieve Relevant Information
      ↓
LLM

This is especially useful for large knowledge bases.

For example:

"What's our refund policy for enterprise customers?"

There is no reason to load:

HR policies
Engineering documentation
Marketing documentation
Old product specifications

The retrieval layer should narrow the information down.

🔍 Retrieval Is a Trade-Off

There is no universal rule that says:

"Always use RAG."

If you have a short document that fits comfortably into the context window and is directly relevant, retrieving chunks may add unnecessary complexity.

For example:

Document: 2 pages
User: "Summarize this document."

Just provide the document.

But if you have:

10 million documents

you obviously cannot send them all.

Retrieval becomes valuable.

The engineering question is:

What information should be available now and what can be fetched later?

3️⃣ Compression — Keep the Meaning, Remove the Bulk

Now let's say we really do need the information.

But the information is huge.

Consider a tool response:

GET /orders/12345

{
    "id": 12345,
    "customer": {...},
    "shipping": {...},
    "billing": {...},
    "items": [...],
    "auditLogs": [...],
    "metadata": {...},
    "internalDebugInformation": {...}
}

Maybe the agent only needs:

Order ID: 12345
Status: FAILED
Payment Status: DECLINED
Failure Reason: Insufficient funds

Why send the entire response?

We can transform:

Large Tool Output
        ↓
Relevant Information
        ↓
Compact Context

This is context compression.

🗜️ Compression Is Not the Same as Deletion

This distinction matters.

Suppose we have:

50 messages

and replace them with:

"The user wants to migrate PostgreSQL
from version 14 to 16 and cannot tolerate
more than 5 minutes of downtime."

We've reduced the number of tokens.

But we also potentially lost information.

Compression is therefore lossy unless the representation preserves everything required for the task.

Recent research on long-horizon agents specifically studies this trade-off: compressing accumulated interaction history can reduce memory requirements while trying to preserve task performance.

So don't blindly summarize everything.

Instead, identify what must survive.

🧠 What Should Survive Compression?

For an agent working on a task, a useful compact state might preserve:

Goal
Current progress
Important decisions
Constraints
Known failures
Important outputs
Pending actions
Relevant identifiers

For example:

Before

User:
We need to migrate the database.

Assistant:
Let's inspect the schema.

Tool:
500 lines...

Assistant:
There are 3 large tables.

Tool:
800 lines...

Assistant:
We should migrate table A first.

Tool:
...

Assistant:
Migration failed because...

...

After compaction

Goal:
Migrate PostgreSQL database.

Progress:
Tables A and B analyzed.

Decision:
Migrate table A first.

Constraint:
Maximum downtime: 5 minutes.

Failure:
Previous migration failed due to missing index.

Next step:
Create the required index and retry.

Much smaller.

But much more useful.

⚠️ Don't Summarize Blindly

This is one of the most important practical lessons.

A generic instruction like:

"Summarize everything above."

doesn't guarantee that the summary will preserve the information your application needs later.

Imagine the original context contains:

Maximum allowed downtime: 5 minutes

If the summary accidentally removes that constraint, the agent might make a technically valid but operationally dangerous decision.

So compression should have explicit preservation rules.

For example:

Always preserve:
- User requirements
- Hard constraints
- IDs
- Decisions
- Pending actions
- Important errors
- Security restrictions

This is much safer than generic summarization.

4️⃣ Caching — Don't Recompute What Hasn't Changed

Now let's talk about something different.

Suppose your application repeatedly sends a large, mostly stable piece of context:

System Instructions
+
Tool Definitions
+
Large Reference Information
+
User Request

If the first three parts rarely change, repeatedly processing them can be wasteful.

That's where prompt caching / provider-side caching mechanisms can help, depending on the model provider.

Conceptually:

┌─────────────────────────────┐
│ Stable Context              │
│                             │
│ System Instructions         │
│ Tool Definitions            │
│ Reference Information       │
└──────────────┬──────────────┘
               │
             CACHE
               │
               ▼
       Current User Request
               │
               ▼
              LLM

The exact caching behavior, eligibility rules, pricing and cache lifetime depend on the provider.

So don't assume:

"Caching means the model remembers everything."

It doesn't.

Caching is an infrastructure optimization, not the same thing as memory.

🧠 Memory ≠ Cache ≠ Context

This is worth clarifying because these concepts are frequently mixed together.

Context

Information available to the model for the current inference.

Current request
+
Relevant history
+
Retrieved information

Memory

Information intentionally retained for future interactions.

User preference
+
Long-term facts
+
Previous task state

Cache

Previously processed/reusable information used to reduce repeated work, depending on the implementation.

Stable prompt prefix
+
Reusable computation

They solve different problems.

5️⃣ Structure — Context Isn't Just About What You Send

There's another subtle aspect:

How you organize the information matters.

Imagine giving an engineer this:

Database:
PostgreSQL

Issue:
Connection timeout

Logs:
...

User:
...

Instructions:
...

Relevant configuration:
...

Versus:

SYSTEM INSTRUCTIONS

TASK

CONSTRAINTS

RELEVANT EVIDENCE

TOOL RESULTS

CURRENT STATE

USER REQUEST

Structured context makes it easier for both developers and models to distinguish different types of information.

A useful pattern is to separate:

Stable information
        +
Dynamic information
        +
Retrieved information
        +
Current task

This also makes your system easier to debug.

When something goes wrong, you can inspect which context component caused the problem.

💰 Token Optimization Is More Than "Use Fewer Tokens"

Suppose an agent executes 20 steps.

And each step sends:

10,000 input tokens

That's potentially:

20 × 10,000
=
200,000 input tokens

across the run.

Now imagine that 6,000 of those tokens were:

Old tool outputs
Repeated instructions
Irrelevant history
Duplicate documents

You may have spent tokens carrying information the model didn't need.

This is why optimizing an agent requires looking at the whole execution, not just one prompt.

Recent work on context optimization explicitly treats long-running agents as a lifecycle problem involving accumulated histories, tool outputs, retrieval and repeated model calls.

📊 Think in Terms of a Context Budget

Instead of asking:

"How much context can my model handle?"

ask:

"How much context should I spend on this task?"

For example:

Context Budget: 20,000 tokens

System Instructions      2,000
Tool Definitions         3,000
Conversation             2,000
Retrieved Documents      5,000
Agent State              2,000
Current Request          1,000
Safety / Constraints     1,000
--------------------------------
Total                   16,000

You still have some room.

But if retrieval suddenly returns:

15,000 tokens

you have a problem.

A context budget makes that visible.

🧹 What Should We Remove First?

When context becomes too large, don't immediately summarize everything.

Use a hierarchy.

First: Remove unnecessary information

Irrelevant tool output
Old duplicate results
Unrelated documents

Then: Reduce verbose outputs

10,000-line log
        ↓
Relevant error lines

Then: Retrieve only what matters

100 documents
        ↓
Top relevant documents

Then: Compress history

50 conversation turns
        ↓
Task state + important decisions

Finally: Consider architectural changes

For example:

Separate agent contexts
Store large artifacts externally
Retrieve information on demand
Split complex tasks

This approach avoids using expensive compression when simple filtering would have solved the problem.

🧰 Keep Large Artifacts Outside the Context

This is particularly important for coding agents and document-heavy systems.

Suppose a tool generates:

50,000 lines of logs

Don't necessarily place all 50,000 lines into the next model request.

Instead:

Tool
 ↓
Large Artifact
 ↓
External Storage
 ↓
Relevant Extract
 ↓
LLM

The model can receive:

"Application crashed at 14:32:08.
Relevant stack trace:
..."

while the complete artifact remains available for retrieval if needed.

This pattern is especially useful when dealing with:

Logs
Large files
Database exports
Build artifacts
Test reports
Large API responses

🧠 Context Engineering Is a Selection Problem

At this point, we can define the problem more precisely.

Every model call has a potential information pool:

                 ALL AVAILABLE INFORMATION
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
       Memory             RAG             Tools
          │                │                │
          └────────────────┼────────────────┘
                           ▼
                     SELECT / RANK
                           │
                           ▼
                       COMPRESS
                           │
                           ▼
                    CONTEXT BUDGET
                           │
                           ▼
                          LLM

The LLM doesn't need everything your system knows.

It needs the right working set for the current decision.

That's perhaps the most important idea in this entire series.

🧪 But How Do You Know Your Context Strategy Is Working?

This is where many AI projects stop too early.

They measure:

Did the model produce a good answer?

But that's not enough.

You should also ask:

Retrieval

Did we retrieve the right documents?
How often are irrelevant documents included?

Context

How large is the context?
Which components consume most tokens?
How often are contexts compressed?

Agent

How many steps does a task require?
How often does the agent repeat a tool call?
How often does it need to recover from an error?

Cost

Input tokens per request
Output tokens
Tokens per successful task
Cache utilization where applicable

Quality

Task success rate
Incorrect answers
Missing information
Failures after compression

A context optimization that saves 50% of tokens but causes 20% more task failures isn't necessarily an optimization.

⚖️ Optimize for Cost and Quality

This is an important mindset.

Don't optimize:

Tokens ↓↓↓

at any cost.

Optimize:

             Quality
                ▲
                │
                │      ●
                │   ●
                │ ●
                └────────────────►
                     Cost

The goal is to find a useful balance between:

Accuracy
Reliability
Latency
Cost
Context size

Sometimes sending more context is absolutely worth it.

Sometimes it isn't.

Context Engineering is about making that decision intentionally.

🚨 Common Context Engineering Mistakes

❌ 1. "Let's send everything"

More context isn't automatically better.

❌ 2. "Let's summarize everything"

Compression can remove information that becomes important later.

❌ 3. "The model has a huge context window, so we're fine"

A large context window is a capability—not a reason to fill it unnecessarily.

❌ 4. "RAG will solve it"

Poor retrieval produces poor context.

RAG doesn't magically make irrelevant documents relevant.

❌ 5. "Just truncate the oldest messages"

The oldest information isn't necessarily the least important.

A previous decision or constraint may still matter.

❌ 6. "We'll optimize tokens later"

Context architecture can affect:

Cost
Latency
Retrieval
Memory
Agent behavior

It becomes increasingly difficult to retrofit once the application grows.

🏗️ A Practical Context Pipeline

Putting everything together:

                         USER REQUEST
                              │
                              ▼
                    ┌──────────────────┐
                    │ Understand Task  │
                    └────────┬─────────┘
                             │
            ┌────────────────┼────────────────┐
            ▼                ▼                ▼
         Memory             RAG             Tools
            │                │                │
            └────────────────┼────────────────┘
                             ▼
                       SELECT RELEVANT
                             │
                             ▼
                       REMOVE NOISE
                             │
                             ▼
                      COMPRESS IF NEEDED
                             │
                             ▼
                       CONTEXT BUDGET
                             │
                             ▼
                            LLM
                             │
                             ▼
                       Evaluate Result
                             │
                    ┌────────┴────────┐
                    │                 │
                 Continue            Done
                    │
                    ▼
              Next Agent Step

This is the mental model I'd keep.

🚀 A Simple Production Checklist

Before shipping an AI feature, ask:

Context

[ ] What information does the model actually need?
[ ] Which information is unnecessary?
[ ] What is retrieved dynamically?
[ ] What is persistent memory?

Tokens

[ ] Do we have a context budget?
[ ] Are large tool outputs filtered?
[ ] Are duplicate documents removed?
[ ] Are long histories compressed when appropriate?

Agents

[ ] What is the maximum number of steps?
[ ] What happens when a tool fails?
[ ] What happens when the model chooses the wrong tool?
[ ] Can the agent loop indefinitely?

Cost & Performance

[ ] Are repeated stable inputs cacheable?
[ ] Are large artifacts kept outside the context?
[ ] Are we measuring tokens per successful task?
[ ] Are we measuring latency?

Quality

[ ] Does compression preserve important constraints?
[ ] Are retrieved documents relevant?
[ ] Are tool results trustworthy and validated?
[ ] Do we have evaluations for context-related failures?

🧠 The Bigger Picture

Let's step back.

When we started this series, Context Engineering sounded like:

"Writing better context for an LLM."

After five parts, we can see that it's much broader.

A production AI system may need to decide:

What should the model see?

        ↓

What should it retrieve?

        ↓

What should it remember?

        ↓

What should it forget?

        ↓

What should be compressed?

        ↓

What should be cached?

        ↓

What should be fetched only when needed?

        ↓

What should the model act on?

        ↓

What should never enter the context?

That is a very different problem from simply writing a better prompt.

🎯 The Five-Part Mental Model

Let's bring the entire series together.

Part 1 — Context Engineering

Give the model the right information.

↓

Part 2 — Tokens, Context & Memory

Understand the constraints around that information.

↓

Part 3 — RAG, Tools & MCP

Retrieve information and connect the model to external capabilities.

↓

Part 4 — AI Agents

Let the system use that context and tools across multiple steps.

↓

Part 5 — Context Optimization

Continuously decide what information should enter, stay, change or leave the context.

And that gives us the bigger picture:

                   USER
                     │
                     ▼
               ┌──────────┐
               │   GOAL   │
               └────┬─────┘
                    │
                    ▼
            ┌───────────────┐
            │ Context Layer │
            │               │
            │ Memory        │
            │ Retrieval     │
            │ Tools         │
            │ History       │
            └───────┬───────┘
                    │
                    ▼
              Select / Rank
                    │
                    ▼
               Compress
                    │
                    ▼
              Context Budget
                    │
                    ▼
                   LLM
                    │
                    ▼
                  Agent
                    │
              ┌─────┴─────┐
              ▼           ▼
           Tool          Done
              │
              ▼
          New Context
              │
              └──────────►

And that loop can continue for as long as the task requires.

🏁 Final Thoughts

One of the biggest shifts happening in AI engineering is that we're moving away from thinking:

"How do I write the perfect prompt?"

and toward:

"How do I build the right information environment for the model at every step?"

That's Context Engineering.

The model matters.

The prompt matters.

But so do:

retrieval, memory, tools, context selection, compression, caching, state, evaluation and orchestration.

And as AI systems become more agentic, this problem becomes even more important.

Because the question isn't simply:

How much can the model see?

It's:

What should the model see right now?

That is the engineering problem.

📌 Key Takeaways

More context isn't automatically better context.
Treat the context window as a resource that needs to be managed.
Remove irrelevant information before trying to compress it.
Retrieve information when it's needed instead of loading everything upfront.
Compress long histories carefully and preserve important decisions, constraints and state.
Keep large artifacts outside the context when possible and retrieve only the relevant portions.
Don't confuse context, memory and caching—they solve different problems.
Set practical token budgets for agent runs.
Measure task success, not just token reduction.
Context optimization is a trade-off between quality, cost, latency and reliability.
The goal isn't to give the model everything.
The goal is to give the model what it needs for the decision it has to make right now.

🤖 AI Context Engineering (Part 4): AI Agents - From Tool Calling to Multi-Step Workflows

Fazal Mansuri — Sat, 08 Aug 2026 07:22:18 +0000

In Part 1, we explored why modern AI systems need more than carefully written prompts.

In Part 2, we looked at tokens, context windows and memory and why simply adding more context doesn't necessarily produce better results.

In Part 3, we went one step further:

RAG helps retrieve relevant information.
Tool Calling lets an AI application interact with external systems.
MCP provides a standardized way for AI applications to interact with tools.

But there's one important question left:

Who decides what should happen next?

Suppose a user asks:

Find the latest failed deployment,
identify the root cause,
create a GitHub issue,
and notify the team on Slack.

That's no longer a single API call.

The system may need to:

1. Find the deployment
2. Retrieve its logs
3. Analyze the failure
4. Decide whether there is enough evidence
5. Create a GitHub issue
6. Send a Slack notification
7. Verify that everything succeeded

Something has to coordinate these steps.

That's where AI agents come in.

🧠 First: What Actually Makes Something an AI Agent?

The word agent is used very loosely today.

Almost every application with an LLM is sometimes called an "AI agent."

That's not particularly useful.

A simple chatbot that answers:

What's the capital of France?

isn't necessarily an agent.

Likewise:

Summarize this document.

doesn't automatically make an application agentic.

A useful way to think about an agent is:

An AI agent is a system where an LLM participates in deciding and executing the steps required to accomplish a goal, often using tools and continuing until a defined completion condition is reached.

The important part is workflow execution.

Instead of:

Input → LLM → Output

we have something closer to:

Goal
 ↓
LLM decides next step
 ↓
Tool / Action
 ↓
Result
 ↓
LLM evaluates result
 ↓
Next step
 ↓
...
 ↓
Final result

This iterative loop is one of the core patterns behind agentic systems.

🔄 The Agent Loop

Let's take a simple example.

The user says:

"Find the latest deployment failure and create a GitHub issue for it."

A possible agent execution could look like:

                    User Goal
                       │
                       ▼
                 ┌───────────┐
                 │    LLM    │
                 └─────┬─────┘
                       │
                Choose next action
                       │
                       ▼
                Deployment Tool
                       │
                       ▼
                Tool Result
                       │
                       ▼
                 ┌───────────┐
                 │    LLM    │
                 └─────┬─────┘
                       │
                 Analyze result
                       │
                       ▼
                 GitHub Tool
                       │
                       ▼
                 Tool Result
                       │
                       ▼
                 ┌───────────┐
                 │    LLM    │
                 └─────┬─────┘
                       │
                       ▼
                 Final Answer

Notice what's different.

The application doesn't necessarily hard-code:

Step 1 → Step 2 → Step 3

Instead, the model can participate in deciding which available action should happen next.

That's the important shift.

🆚 Workflow vs Agent

This distinction is extremely important.

Imagine you have:

Step 1 → Fetch Order
Step 2 → Validate Payment
Step 3 → Generate Invoice
Step 4 → Send Email

The sequence is always the same.

You probably don't need an agent.

A normal deterministic workflow is simpler.

User
 ↓
Fetch Order
 ↓
Validate Payment
 ↓
Generate Invoice
 ↓
Send Email

Now consider:

Investigate why this customer's order failed.

You don't necessarily know beforehand what steps are required.

The system might need to:

Look up the order
Check payment status
Inspect inventory
Search support tickets
Check logs
Compare previous attempts
Decide whether another investigation is necessary

The path depends on what the system discovers.

That's a much better candidate for an agent.

A useful rule:

If the workflow is predictable, prefer deterministic code. If the workflow requires dynamic decisions over multiple steps, an agent may be useful.

Even current agent guidance recommends starting with simpler deterministic approaches where they are sufficient rather than introducing unnecessary autonomy.

🧩 An Agent Is Not "Just an LLM"

A production agent normally consists of several pieces.

At a high level:

             ┌───────────────────┐
             │       Agent       │
             │                   │
             │   Instructions    │
             │        +          │
             │       LLM         │
             └─────────┬─────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Memory         RAG         Tools
          │            │            │
          ▼            ▼            ▼
       State        Knowledge    Actions

The model is only one component.

The surrounding system provides:

Instructions
Tools
Context
State
Memory
Guardrails
Execution limits
Observability

This is exactly where Context Engineering becomes especially important.

📦 The Agent's Context Keeps Changing

Here's an important connection to Parts 1–3.

In a simple LLM request:

User
 ↓
Prompt
 ↓
LLM

the context is relatively straightforward.

But an agent might execute several actions.

After the first tool:

User request
+
Tool result

After the second:

User request
+
Tool result 1
+
Tool result 2

After the third:

User request
+
Tool result 1
+
Tool result 2
+
Tool result 3

And so on.

If you keep everything forever, the context can become unnecessarily large.

Remember Part 2:

More context ≠ better context.

An agent therefore needs to manage context carefully.

It may need to:

Keep important state
Remove irrelevant tool output
Summarize previous steps
Retrieve information again when necessary
Preserve the user's original goal
Track what has already been completed

This is one reason agent engineering and context engineering are deeply connected.

🔧 Tools Give Agents Their Hands

We discussed Tool Calling in Part 3.

Now look at it from the agent's perspective.

A tool might expose:

get_order(order_id)

Another:

get_payment_status(order_id)

Another:

create_github_issue(title, body)

Another:

send_slack_message(channel, message)

The agent can decide which tool is useful for the current step.

Conceptually:

User Goal
   │
   ▼
  Agent
   │
   ├── get_order()
   │
   ├── get_payment_status()
   │
   ├── create_github_issue()
   │
   └── send_slack_message()

But there's an important engineering principle here:

Giving an agent a tool does not mean the agent should always be allowed to use it.

A tool that reads data is very different from a tool that:

delete_database()

or:

transfer_money()

or:

send_email()

This is where guardrails become critical.

🛑 Agents Need Boundaries

Autonomy sounds exciting until the system makes the wrong decision.

Imagine an agent has this tool:

delete_customer()

The model interprets a user's request incorrectly.

Without safeguards:

User
 ↓
LLM
 ↓
delete_customer()
 ↓
💥

A production system should instead introduce controls.

User
 ↓
Agent
 ↓
Tool Request
 ↓
Permission Check
 ↓
Validation
 ↓
Human Approval? ── Yes ──→ Human
 ↓ No
Execute Tool

Depending on the action, you might require:

Authentication
Authorization
Input validation
Business-rule validation
Rate limits
Human approval
Audit logging

The more consequential the action, the stronger the controls should be.

Agent systems therefore aren't just an AI problem.

They're also a systems engineering and security problem. Current agent guidance explicitly treats guardrails and controlled tool access as important parts of agent design.

🔁 What About ReAct?

You may have heard the term ReAct while reading about AI agents.

ReAct stands for:

Reason + Act

The research introduced a pattern where a model alternates between reasoning about a task and taking actions through tools, using the resulting observations to continue the task.

Conceptually:

Question
   ↓
Reason
   ↓
Action
   ↓
Observation
   ↓
Reason
   ↓
Action
   ↓
Observation
   ↓
Final Answer

For example:

User:
"Why did deployment #482 fail?"

The agent might need to:

→ Get deployment #482
→ Inspect failure details
→ Retrieve relevant logs
→ Analyze the error
→ Decide whether more information is needed
→ Produce an explanation

The important lesson isn't:

"Every agent must use ReAct."

It shouldn't be treated that way.

ReAct is one influential approach to combining reasoning and action. Modern agent systems can use different orchestration strategies depending on the problem.

👨‍💻 What Does an Agent Loop Look Like in Go?

You don't need an AI framework to understand the underlying architecture.

At its core, an agent can be thought of as a loop.

Here's a simplified orchestration skeleton:

type ToolResult struct {
    Name   string
    Output string
}

type AgentDecision struct {
    ToolName string
    Input    string
    Done     bool
    Answer   string
}

func runAgent(ctx context.Context, goal string) (string, error) {
    var history []ToolResult

    for step := 0; step < 10; step++ {
        decision, err := askModel(ctx, goal, history)
        if err != nil {
            return "", err
        }

        if decision.Done {
            return decision.Answer, nil
        }

        tool, ok := getTool(decision.ToolName)
        if !ok {
            return "", fmt.Errorf("unknown tool: %s", decision.ToolName)
        }

        result, err := tool.Execute(ctx, decision.Input)
        if err != nil {
            return "", err
        }

        history = append(history, ToolResult{
            Name:   decision.ToolName,
            Output: result,
        })
    }

    return "", errors.New("agent exceeded maximum steps")
}

The important part isn't the exact implementation.

It's the architecture:

        ┌───────────────┐
        │   Ask Model   │
        └───────┬───────┘
                │
                ▼
        Tool needed?
          /       \
        Yes        No
         │          │
         ▼          ▼
     Execute      Finish
       Tool
         │
         ▼
    Tool Result
         │
         └──────────────┐
                        │
                        ▼
                   Ask Model

Notice the safety mechanism:

for step := 0; step < 10; step++ {

That's not just an implementation detail.

It's an execution boundary.

Without a maximum number of steps, a poorly behaving agent could continue looping indefinitely.

Real systems need explicit termination conditions and failure handling. Agent orchestration commonly uses limits such as maximum turns, successful final output, tool completion or errors to stop execution.

⚠️ Why "Fully Autonomous" Isn't Always Better

There's a tendency to think:

More autonomy
     =
Better agent

Not necessarily.

Imagine two systems.

System A

Agent
 ↓
20 tools
 ↓
Unlimited steps
 ↓
No approval
 ↓
No validation

It sounds powerful.

It is also difficult to predict, debug, secure and operate.

System B

Agent
 ↓
5 well-defined tools
 ↓
Maximum 8 steps
 ↓
Permission checks
 ↓
Human approval for risky actions
 ↓
Full tracing

System B may be much more useful in production.

The goal isn't maximum autonomy.

The goal is:

Enough autonomy to solve the problem while keeping behavior observable, bounded and controllable.

🧠 Single Agent vs Multi-Agent

Once developers understand agents, another idea quickly appears:

"Why not create multiple agents?"

For example:

                Manager Agent
                 /     |     \
                /      |      \
               ▼       ▼       ▼
          Research   Coding   Testing
            Agent     Agent    Agent

This can be useful for genuinely different responsibilities.

But it also introduces additional complexity:

More model calls
More context passing
More failure points
More latency
More difficult debugging
More coordination logic

You don't need multiple agents just because you can build them.

A single agent with good tools can often handle many workflows.

A sensible progression is:

Deterministic Workflow
        ↓
Single Agent
        ↓
Multiple Specialized Agents

Move to the next level only when the problem actually requires it. Current agent design guidance similarly recommends starting incrementally rather than immediately building complex multi-agent architectures.

🔍 The Part Developers Often Miss: Observability

Here's where agent systems become very different from normal APIs.

Imagine your API returns:

500 Internal Server Error

You inspect logs.

Fine.

But an agent might fail because:

User Request
    ↓
Tool A
    ↓
Tool B
    ↓
Wrong tool selected
    ↓
Bad result
    ↓
Agent makes another decision
    ↓
Final answer is incorrect

The final output alone doesn't tell you what happened.

You need visibility into the execution trace.

For example:

Run ID: 8f21

Step 1
Tool: search_deployments
Input: production
Result: deployment #482

Step 2
Tool: get_logs
Input: #482
Result: database connection timeout

Step 3
Tool: search_docs
Input: database connection timeout
Result: connection pool documentation

Step 4
Decision: create GitHub issue

Step 5
Tool: create_issue
Result: issue #921

This makes agent behavior much easier to debug.

Observability and tracing are now treated as important parts of production agent development because the system's behavior spans multiple model and tool steps.

🧩 The Complete Picture

Now let's connect everything from Parts 1–4.

A modern AI application might look like this:

                         USER
                           │
                           ▼
                  ┌─────────────────┐
                  │  AI Application │
                  └────────┬────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    AGENT    │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
             RAG         Tools        Memory
              │            │            │
              └────────────┼────────────┘
                           ▼
                    Context Builder
                           │
                           ▼
                          LLM
                           │
                           ▼
                    Next Decision
                           │
                           └──────→ Tool / RAG
                                      │
                                      └──→ ...

This is where the entire series starts to come together.

📌 The Mental Model

If you remember only four things from this article, remember this:

Part 1 - Context Engineering

Give the model the right information for the task.

Part 2 - Context Management

Don't confuse more context with better context.

Part 3 - RAG + Tools + MCP

Retrieve knowledge and give the system controlled access to external capabilities.

Part 4 - Agents

Let the system decide and execute multiple steps toward a goal-within defined boundaries.

That's the progression.

Prompt
  ↓
Context
  ↓
Context + Tools
  ↓
Context + Tools + Decisions
  ↓
Agent

🚨 When Should You NOT Build an Agent?

This might be the most important advice in the entire article.

If your workflow is:

Receive Request
     ↓
Validate
     ↓
Insert Database Row
     ↓
Return Response

Don't build an agent.

Use normal application code.

If your workflow is:

Understand user's goal
     ↓
Find relevant information
     ↓
Choose among several tools
     ↓
Inspect results
     ↓
Decide what to do next
     ↓
Possibly perform more actions
     ↓
Stop when the goal is satisfied

An agent may make sense.

Use agents where dynamic decision-making provides real value-not simply because agents are trending.

🎯 Key Takeaways

An AI agent is more than an LLM wrapped in a chatbot.
Agents use models to participate in multi-step workflow execution.
Tools allow agents to retrieve information or take actions.
An agent typically operates through an iterative loop: decide → act → observe → decide again.
RAG provides knowledge; tools provide capabilities.
Context changes as an agent executes more steps, making context management especially important.
Not every workflow needs an agent. Deterministic workflows are often simpler and more predictable.
Agents should have explicit boundaries such as step limits, permissions, validation and approval for sensitive actions.
Observability is critical because the final answer doesn't tell you everything that happened during an agent run.
Multi-agent systems can be useful, but they also introduce additional complexity and should not be the default.
The goal isn't maximum autonomy. It's useful autonomy with control.

🚀 What's Next?

We've now built the foundation:

Part 1: What is Context Engineering?

Part 2: Tokens, Context Windows & Memory

Part 3: RAG, Tool Calling & MCP

Part 4: AI Agents & Multi-Step Workflows

But there's a problem.

An agent can have:

Thousands of documents
Dozens of tools
Long conversation history
Multiple tool results
Previous execution state

And if we keep putting everything into the context...

💸 Token costs increase.

🐌 Latency increases.

🧠 Relevant information gets buried.

And eventually, simply giving the model more context can make the system worse.

So the next question becomes:

How do we decide what context an AI actually needs-and what should be removed?

That's where we go next.

AI Context Engineering - Part 5: Context Optimization

We'll look at practical techniques such as:

Context compression
Summarization
Relevance ranking
Context pruning
Caching
Token optimization
Context prioritization
And how to reduce cost without sacrificing useful information

Because in production AI systems:

The goal isn't to give the model everything.

The goal is to give it exactly what it needs. 🚀

🚀 AI Context Engineering (Part 3): How AI Actually Finds Information - RAG, Tool Calling & MCP Explained

Fazal Mansuri — Sat, 25 Jul 2026 06:49:16 +0000

In Part 1, we explored why modern AI systems need more than just good prompts.

In Part 2, we learned how tokens, context windows, and memory shape the quality of an AI application's responses.

By now, we know one important fact:

The quality of an AI system depends heavily on the quality of the context it receives.

But that naturally raises another question.

Where does all that context actually come from?

Imagine asking an AI assistant:

What is our company's leave policy?

Or perhaps:

Explain this private function in our GitHub repository.

Or even:

How many orders were placed today?

How can an AI answer questions about information that was never part of its training data?

It wasn't trained on your company's HR handbook.

It doesn't know your private GitHub repository.

It certainly doesn't know how many orders your application processed five minutes ago.

Yet modern AI applications answer these questions surprisingly well.

How?

Because today's AI applications do far more than simply send your prompt to a language model.

They search, retrieve, call tools, and assemble relevant information before asking the model to generate a response.

That's exactly what we'll explore in this article.

🧠 The Biggest Misconception About AI

Many people imagine AI applications working like this:

It feels simple.

Ask a question.

Receive an answer.

But modern AI systems are much more sophisticated.

A more accurate picture looks like this:

Notice something important.

The LLM isn't doing everything.

Instead, the application surrounding the LLM is responsible for gathering the right information before asking the model to generate a response.

This is Context Engineering in practice.

Why Language Models Don't Know Everything

Large Language Models are trained on enormous amounts of publicly available text.

That training gives them remarkable reasoning and language capabilities.

However, training has limits.

A model typically cannot know:

Your company's internal documentation
Private GitHub repositories
Customer databases
Current inventory
Live weather
Today's stock prices
This morning's support tickets
The latest production deployment

Even if the information exists somewhere, it may have been created after the model finished training.

This distinction is important.

The model isn't "searching the internet" every time you ask a question.

Instead, the surrounding application decides whether additional information needs to be retrieved.

📚 Retrieval-Augmented Generation (RAG)

One of the most common techniques for providing that information is called Retrieval-Augmented Generation, commonly known as RAG.

The name sounds complicated.

The idea isn't.

Think about an open-book exam.

During the exam, you're allowed to search the textbook.

You don't memorize every page beforehand.

Instead, you:

Read the question.
Find the relevant chapter.
Read only those pages.
Write the answer.

That's exactly how RAG works.

The language model doesn't memorize every document.

Instead, the application retrieves relevant information first, then includes it as part of the context sent to the model.

Conceptually:

The model hasn't learned anything new.

It simply received better context.

RAG Does Not Retrain the Model

This is another common misconception.

Sometimes people say:

"We added documents to our RAG system, so we trained the model."

That's not how RAG works.

Training changes the model's parameters through a computationally intensive learning process.

RAG doesn't modify the model at all.

Instead, it changes the information available during inference.

Think of it this way.

Training is like teaching someone a new language.

RAG is like handing them the correct reference book before asking a question.

The person's knowledge hasn't changed.

They simply have access to additional information.

A Practical Example

Suppose your company has thousands of pages of internal documentation.

A developer asks:

How do I deploy the billing service?

Without RAG:

The model can only rely on general knowledge.

It might produce a reasonable deployment process - but not your company's process.

With RAG:

The application first searches your documentation.

Perhaps it retrieves:

Billing deployment guide
Kubernetes manifest
Environment variables
Rollback procedure

Only these relevant documents are attached to the request.

The model now has enough context to generate an accurate answer.

Notice something interesting.

The user still asked the same question.

The improvement came entirely from better context.

🎯 Good RAG Isn't About Retrieving More

Many beginners assume:

More documents = Better answer

Usually, the opposite is true.

Imagine asking:

How do I reset my password?

Would you rather provide:

The password reset documentation

Every document in your company?

Clearly, the first option is better.

The goal of RAG isn't to retrieve everything.

The goal is to retrieve only what matters.

This connects directly to what we learned in Part 2.

Remember:

More context doesn't automatically produce better answers.

Retrieving unnecessary information wastes tokens, increases latency, and may distract the model from the information that actually matters.

Good RAG systems focus on precision, not volume.

A Simple Go Example

Imagine you have internal documentation stored in a database.

Without RAG, your application might simply forward the user's question to the LLM:

prompt := "How do I deploy the billing service?"

response := callLLM(prompt)

The model has no access to your documentation.

Now imagine a simplified RAG workflow.

question := "How do I deploy the billing service?"

docs := searchKnowledgeBase(question)

context := fmt.Sprintf(`
Relevant Documentation:

%s

User Question:
%s
`, strings.Join(docs, "\n\n"), question)

response := callLLM(context)

Notice something important.

The model wasn't changed.

The only difference is that your application retrieved relevant information before sending the request.

That's the essence of Retrieval-Augmented Generation.

How Does the Application Find the Right Documents?

At this point, you might be wondering:

"How does the application know which documents are relevant?"

That's an excellent question.

Modern RAG systems typically rely on embeddings and vector search to retrieve semantically similar documents rather than performing simple keyword matching.

Those topics deserve their own deep dive because they involve concepts like:

Embedding models
Vector databases
Similarity search
Chunking strategies
Ranking

For now, it's enough to understand that the retrieval system attempts to find the most relevant pieces of information and passes only those into the context.

The important takeaway is this:

The LLM isn't searching your documents directly. The application retrieves them first.

🤖 Retrieval Gives Knowledge. But What If the AI Needs to Take an Action?

So far, we've looked at questions like:

What is our refund policy?

Explain this deployment guide.

These are knowledge retrieval problems.

But now consider a different request.

Create a new GitHub issue.

Or:

Send this report to Slack.

Or:

Book a meeting for tomorrow at 3 PM.

Reading documentation isn't enough anymore.

The AI now needs to perform an action.

How does that happen?

Does the language model directly call APIs?

Can it create GitHub issues on its own?

Can it send Slack messages by itself?

Not quite.

This is where Tool Calling enters the picture - and it's one of the most misunderstood concepts in modern AI systems.

🔧 Tool Calling: Giving AI the Ability to Act

So far, we've seen how RAG helps AI answer questions by retrieving relevant information.

But sometimes answering a question isn't enough.

Imagine asking an AI assistant:

Create a GitHub issue titled "Fix login bug".

Or:

Send today's deployment report to Slack.

Or:

What's the current CPU usage of our production server?

These aren't knowledge problems anymore.

They're action problems.

The AI now needs to interact with external systems.

This is where Tool Calling comes into the picture.

🤔 Does the LLM Execute APIs?

One of the biggest misconceptions is that language models directly execute code or call APIs.

They don't.

A Large Language Model generates text.

That's its primary capability.

When an application enables Tool Calling, the model can decide:

"To answer this request correctly, I need to use a specific tool."

The application then executes that tool and returns the result to the model.

The model never talks to GitHub, Slack, or your database directly.

The application does.

Think of it like this:

The LLM makes the decision.

The application performs the action.

This separation is important because it allows developers to validate permissions, handle authentication, retry failures, log requests, and control exactly what the model is allowed to do.

A Simple Go Example

Suppose your application exposes a tool for fetching the current weather.

type WeatherTool struct{}

func (WeatherTool) Execute(city string) (string, error) {
    return fmt.Sprintf("%s: 29°C, Clear Sky", city), nil
}

When a user asks:

What's the weather in Ahmedabad?

The application might work like this:

tool := WeatherTool{}

weather, err := tool.Execute("Ahmedabad")
if err != nil {
    log.Fatal(err)
}

prompt := fmt.Sprintf(`
Weather Information:

%s

Answer the user's question naturally.
`, weather)

response := callLLM(prompt)

fmt.Println(response)

Notice something important.

The weather API wasn't called by the language model.

It was called by your Go application.

The model simply received the weather information as additional context before generating the response.

Once again, Context Engineering is doing the heavy lifting.

📚 RAG Retrieves Knowledge. Tools Perform Actions.

This distinction is worth remembering.

Imagine asking these questions:

What is our leave policy?

You need documentation.

RAG is the right choice.

Approve leave request #1245.

Now the AI must interact with your HR system.

A tool needs to execute that action.

Another example:

Explain today's failed deployment.

Retrieve deployment logs.

RAG.

Restart the Kubernetes deployment.

Execute kubectl or a deployment API.

Tool Calling.

One retrieves information.

The other performs work.

Many production AI applications use both together.

🧩 What Happens When You Have Hundreds of Tools?

Now imagine your AI assistant can interact with:

GitHub
Jira
Slack
Google Drive
PostgreSQL
Filesystem
Kubernetes
AWS
Internal APIs

Each system exposes its own:

Authentication
API format
Documentation
SDK
Request structure

Without standardization, integrating each tool becomes increasingly complex.

That's exactly the problem Model Context Protocol (MCP) was designed to solve.

🌉 What Is MCP?

Think of USB.

Before USB existed:

Every device required a different connector.

Different cables.

Different ports.

Different drivers.

USB introduced a common standard.

Manufacturers still built different devices.

But computers interacted with them in a consistent way.

MCP plays a similar role for AI applications.

Instead of every tool exposing a completely different interface, MCP defines a standard way for AI applications to discover and interact with tools.

The protocol doesn't replace your APIs.

It standardizes how AI systems communicate with them.

🏗️ A Simplified MCP Architecture

Each MCP server exposes capabilities using the same protocol.

The client no longer needs to understand dozens of different integrations individually.

This makes adding new tools significantly easier.

MCP Is Not a Replacement for APIs

Another common misconception is:

"MCP replaces REST APIs."

It doesn't.

REST APIs still exist.

Databases still exist.

GitHub APIs still exist.

Slack APIs still exist.

MCP simply provides a standardized interface that AI applications can use to interact with those systems more consistently.

Think of MCP as a translator sitting between AI applications and external tools.

Putting It All Together

Let's revisit our original question:

Create a GitHub issue summarizing today's failed deployment.

Here's what might happen behind the scenes.

                    User
                      │
                      ▼
            AI Application
                      │
      ┌───────────────┼────────────────┐
      ▼                                ▼
Retrieve Deployment Logs        GitHub Tool
      │                                │
      └───────────────┬────────────────┘
                      ▼
             Build Context
                      │
                      ▼
                    LLM
                      │
                      ▼
      "Create issue titled...
       Include deployment summary..."

Notice something interesting.

This single request used:

Retrieval (deployment logs)
Tool Calling (GitHub)
Context Engineering (combining everything)
The LLM (reasoning and language generation)

Modern AI assistants rarely rely on only one technique.

They're orchestration systems.

RAG vs Tool Calling vs MCP

These concepts are often confused because they frequently appear together.

Here's an easy way to distinguish them.

Feature	RAG	Tool Calling	MCP
Primary Goal	Retrieve information	Execute actions	Standardize tool integrations
Changes external state	❌ No	✅ Yes (can)	Depends on the tool
Reads knowledge	✅ Yes	Sometimes	Depends
Calls external systems	Indirectly	✅ Yes	Provides the interface
Typical Example	Company documentation	GitHub, Slack, Database	GitHub MCP Server

The important point is that these technologies complement one another rather than compete.

🧠 A Simple Mental Model

Whenever you're unsure which concept applies, ask yourself one question:

"What is the AI trying to do?"

If the answer is:

Find information

→ Think RAG

Perform an action

→ Think Tool Calling

Connect AI to many different tools consistently

→ Think MCP

This simple mental model eliminates much of the confusion surrounding these terms.

🚀 Production Best Practices

If you're building AI-powered applications, keep these principles in mind.

✅ Retrieve only relevant information

More documents don't automatically improve answers.

High-quality retrieval almost always beats high-volume retrieval.

✅ Keep retrieved context concise

Every additional token increases cost and latency.

Only include information that helps answer the current question.

✅ Design tools to do one thing well

Instead of creating one massive "do everything" tool, expose smaller, focused capabilities.

They're easier for both developers and language models to use correctly.

✅ Validate every tool invocation

Never assume the model made the correct decision.

Your application should validate permissions, inputs, authentication, and business rules before executing any action.

✅ Treat tool outputs as untrusted input

External systems can fail.

APIs can return unexpected data.

Always handle errors gracefully before sending results back to the model.

✅ Monitor retrieval quality

Poor RAG often isn't caused by the language model.

It's caused by retrieving the wrong documents.

Measure retrieval quality just as carefully as you evaluate model responses.

🏁 Final Thoughts

When people first begin exploring AI, they often focus on the language model itself.

But as you've seen throughout this series, the model is only one part of the system.

The real intelligence often comes from the application surrounding it.

That application decides:

What information should be retrieved.
Which tools should be available.
How context is assembled.
What actions are permitted.
How responses are validated.

This is why two applications built on the same underlying model can produce dramatically different results.

The difference usually isn't the model.

It's the quality of the surrounding engineering.

And that's exactly what Context Engineering is all about.

📌 Key Takeaways

Large Language Models don't automatically know your private or real-time data.
RAG improves responses by retrieving relevant information before sending the request to the model.
RAG doesn't retrain or modify the model - it enriches the context during inference.
Tool Calling enables AI applications to perform actions by letting the application execute external operations.
The language model decides when a tool is needed, but the application executes it.
MCP provides a standardized way for AI applications to interact with many different tools.
Effective AI systems combine retrieval, tool execution, and carefully constructed context to produce accurate and useful responses.

🚀 Coming Up in Part 4

So far, we've explored:

Why prompts alone aren't enough.
How tokens and context windows influence AI.
How AI retrieves information and interacts with external tools.

But one fascinating question still remains:

How does an AI decide what to do first?

If a request requires searching documentation, querying a database, calling multiple APIs, verifying results, and finally generating a response…

Who plans those steps?

Who decides whether another tool should be used?

Who determines that the answer needs to be checked before responding?

That's where AI Agents come in.

In Part 4, we'll go beyond the buzzword and explore how modern AI agents think, plan, reason and orchestrate complex workflows - along with the patterns that power today's most capable AI systems.

📦 AI Context Engineering (Part 2): Tokens, Context Windows & Memory - Why More Context Isn't Always Better

Fazal Mansuri — Sun, 05 Jul 2026 06:23:35 +0000

In Part 1, we learned that building great AI applications isn't just about writing better prompts.

It's about providing the right context.

But that naturally leads to another question:

How much context can an AI actually understand?

If you've used ChatGPT, Claude, Gemini, Cursor or any AI coding assistant for a while, you've probably experienced something like this.

🤔 "Didn't I Already Tell You That?"

Imagine you're debugging a production issue with an AI assistant.

You start by explaining the architecture.

Then you share the API flow.

Then database schema.

Then logs.

Then stack traces.

After 30 minutes of conversation, you ask:

"So what's causing the bug?"

Instead of giving the answer, the AI responds:

"Could you share your database schema?"

You stare at the screen.

"I already did..."

Sometimes it even forgets details from earlier in the same conversation.

Naturally, people assume:

The AI has bad memory.
The model is unreliable.
The conversation is broken.

In reality, something completely different is happening.

You're running into one of the most important concepts in modern AI systems:

The Context Window.

Understanding this concept changes how you interact with AI—and more importantly, how you build AI-powered applications.

🧠 Before We Talk About Context Windows…

We first need to understand something much smaller.

Tokens.

Almost every AI provider mentions them.

Pricing is based on them.

Context windows are measured using them.

Yet many developers still think:

1 token = 1 word

That isn't true.

🔤 What Exactly Is a Token?

A token is the basic unit of text that an AI model processes.

Humans naturally read text as:

Characters
Words
Sentences

Large Language Models don't.

Before text reaches the model, it's converted into smaller pieces called tokens by a tokenizer.

The model never sees your original sentence.

It only sees a sequence of tokens.

Think of a tokenizer as a translator between humans and AI.

You write English
        ↓
Tokenizer
        ↓
Sequence of Tokens
        ↓
LLM

The tokenizer decides how text is split.

And that's why tokens aren't the same as words.

Tokens ≠ Words

This is probably the biggest misconception about LLMs.

Consider this sentence:

Hello World

You might expect:

2 words = 2 tokens

Sometimes that's true.

Sometimes it isn't.

Now consider:

internationalization

One word.

But depending on the tokenizer, it may be split into multiple tokens because the model has learned common sub-word patterns rather than every possible English word.

Similarly:

authentication
authorization
microservices

may also become multiple tokens.

The tokenizer isn't trying to understand grammar.

It's trying to represent text efficiently based on patterns it learned during training.

📦 Different Types of Content Produce Different Numbers of Tokens

One reason token counting surprises developers is that not all text is equal.

Take these examples.

Example 1 — Simple English

The server is running normally.

This is relatively efficient because it contains common words.

Example 2 — JSON

{
  "userId": 123,
  "isActive": true
}

Even though this looks short, punctuation, quotes, braces and field names also become tokens.

Example 3 — Source Code

if err != nil {
    return err
}

Programming languages introduce symbols, keywords, indentation and identifiers, all of which contribute to the token count.

Example 4 — URLs

https://example.com/api/v1/users/123

URLs often tokenize differently because of slashes, punctuation and path segments.

Example 5 — Emojis

🚀🔥🎉

Even emojis are tokenized.

Different models may tokenize the same emoji sequence differently.

💡 The Important Lesson

Tokens are not based on what humans consider words.

They're based on how the tokenizer breaks text into pieces.

That's why two pieces of text with the same number of characters can consume very different numbers of tokens.

🎯 Why Should Developers Care About Tokens?

Many developers only think about tokens when they receive an API bill.

In reality, tokens influence almost everything about an AI system.

They affect:

Cost
Latency
Context size
Response quality
Memory
Scalability

Every AI request starts with a token budget.

The more tokens you consume, the more work the model has to perform.

💰 Everything Consumes Tokens

Here's something many people don't realize.

When you send a request to an LLM, you're not paying only for your latest prompt.

The model processes everything included in the request.

That may include:

Content	Uses Tokens?
System Instructions	✅
User Prompt	✅
Conversation History	✅
Uploaded Documents	✅
Retrieved RAG Results	✅
Tool Outputs	✅
Function Call Results	✅
AI Response	✅

Even if you only typed:

Summarize this.

The model might actually receive thousands of tokens.

Imagine asking an AI coding assistant:

Why is this function failing?

Behind the scenes, the application might automatically include:

System instructions
Current source file
Nearby functions
Package imports
Build configuration
Previous conversation
Compiler errors

Your four-word prompt becomes a request containing thousands of tokens.

This is another example of Context Engineering in action.

🔄 Every New Request Starts Again

This surprises many engineers.

Suppose your conversation looks like this:

User:
Explain JWT Authentication.

Assistant:
...

User:
Can you show a Go example?

Assistant:
...

User:
Can you make it use middleware?

Many people imagine the model simply remembers everything internally.

That's not how most stateless LLM API interactions work.

For each new request, the application typically sends the conversation history (or a selected portion of it) again so the model has the necessary context to continue the conversation coherently.

Conceptually, it looks something like this:

Request 1

System Prompt
User Message

↓

LLM

------------------------

Request 2

System Prompt
Conversation History
New User Message

↓

LLM

------------------------

Request 3

System Prompt
Conversation History
Latest User Message

↓

LLM

As the conversation grows longer, more tokens are often included with each request unless the application trims, summarizes or otherwise manages the context.

This is one reason token usage can increase significantly during long conversations.

🪟 What Is a Context Window?

Now we can finally answer the question from the beginning.

If tokens are the building blocks…

Then what is the Context Window?

A context window is the maximum amount of information (measured in tokens) that a model can consider at one time while generating a response.

Think of it like a whiteboard.

Imagine you're solving a difficult problem with a teammate.

Everything written on the whiteboard is available to both of you.

You can read it.

Reference it.

Connect ideas.

Reason about it.

But the whiteboard isn't infinite.

Eventually, it fills up.

To continue working, you have two choices:

Erase older notes.
Replace them with a summary.

Large Language Models work in a very similar way.

The context window is that whiteboard.

Everything currently inside it is visible to the model while it generates its next response.

Everything outside it is invisible unless your application decides to bring it back.

📖 What's Actually Inside the Context Window?

One common misconception is that the context window contains only your prompt.

In reality, modern AI applications often build a much richer context before sending the request.

A simplified request might look like this:

System Instructions

↓

Conversation History

↓

Retrieved Knowledge (RAG)

↓

Uploaded Files

↓

Tool Results

↓

Current User Prompt

↓

LLM

Notice something interesting.

Your latest message may only be a tiny fraction of everything the model receives.

The application has already assembled the rest of the context behind the scenes.

This is why two AI tools using the same underlying model can produce very different answers.

The difference often isn't the model itself.

It's how effectively each application constructs the context before making the request.

🤔 Does a Bigger Context Window Always Mean Better AI?

At first glance, it sounds obvious.

If an AI model can process more information, shouldn't the answers always improve?

Not necessarily.

Imagine you're preparing for an interview.

Someone gives you:

Your resume
The job description
Company documentation
Engineering handbook
API documentation
Meeting notes
Internal wiki
Product roadmap
Last year's planning documents
Random Slack conversations

Could you answer the interview questions?

Probably.

Would all that information actually help?

Probably not.

In fact, it might make things worse because you'd spend time filtering out irrelevant information before focusing on what matters.

Large Language Models face a similar challenge.

A larger context window allows the model to see more information, but it doesn't mean every piece of that information is equally useful.

Good Context Engineering isn't about maximizing context.

It's about optimizing context.

🎯 More Context ≠ Better Context

One of the biggest mistakes in AI applications is thinking:

If some context helps,
more context must help even more.

That's rarely true.

Imagine building an AI coding assistant.

A developer asks:

Why is this API returning 500?

Option A:

Provide only:

The API handler
Relevant service
Error log

Option B:

Provide:

Entire repository
All dependencies
Every README
CI/CD configuration
Kubernetes manifests
Previous conversations
All database schemas

Technically, the model has more information.

Practically, you've introduced noise.

Finding the relevant signal becomes harder.

This is why mature AI systems spend significant effort deciding what not to include.

Context Engineering is often about removing information rather than adding it.

🔍 The "Lost in the Middle" Problem

Researchers have observed an interesting behavior in long-context language models.

When a prompt becomes very large, information buried in the middle of the context may receive less attention than information closer to the beginning or end.

This phenomenon is commonly referred to as the "Lost in the Middle" effect.

Imagine reading a 300-page document.

You usually remember:

The introduction
The conclusion

But details from page 147?

Much harder.

Language models can exhibit similar behavior under certain conditions.

This doesn't mean long-context models are ineffective.

It means that how information is organized inside the context matters, not just how much information is included.

🧠 Context Is NOT Memory

This is probably the biggest misconception about modern AI.

People often say:

"ChatGPT remembered what I told it last week."

What actually happened depends on the application.

It's important to distinguish between context and memory.

Context

Context is the information available only for the current request.

Once the request is complete, the model itself doesn't retain that context for future API calls.

Think of it as a whiteboard used during a meeting.

Erase the whiteboard and the discussion is gone.

Memory

Memory is information that an application intentionally stores and later reintroduces into future conversations.

For example:

You tell an AI assistant:

I primarily write Go and React.

The application might choose to save that preference.

Next week, when you ask:

Generate an API example.

The application retrieves your stored preference and injects it into the new request.

The model appears to "remember."

In reality, the application supplied that information again.

The memory lives in the application—not inside the language model itself.

🏗️ A Simple Mental Model

Think of an AI application as three separate components:

                User

                  │
                  ▼

      ┌─────────────────────┐
      │   Memory Store      │
      └─────────────────────┘
                  │
                  ▼
      ┌─────────────────────┐
      │ Context Builder     │
      │ - System Prompt     │
      │ - History           │
      │ - RAG Results       │
      │ - Tool Outputs      │
      └─────────────────────┘
                  │
                  ▼
      ┌─────────────────────┐
      │        LLM          │
      └─────────────────────┘

The LLM only sees the final assembled context.

It doesn't know where each piece of information came from.

💰 Why Tokens Matter for Cost and Performance

We've already learned that everything consumes tokens.

But token usage affects much more than pricing.

It also impacts:

Request latency
Throughput
Infrastructure cost
User experience

Consider these two requests.

Efficient Request

System Prompt

Relevant API documentation

Current User Question

Inefficient Request

System Prompt

Entire conversation

Complete codebase

Multiple PDFs

Large JSON payloads

Old logs

Current User Question

The second request requires the model to process significantly more information before generating a response.

Even if the answer only depends on a small portion of that data.

More tokens generally mean:

More computation
Higher latency
Higher cost

This is why production AI systems invest heavily in efficient context management.

⚙️ How Production AI Systems Manage Context

Well-designed AI applications rarely send everything they know to the model.

Instead, they carefully construct the context.

Some common strategies include:

✅ Retrieve Only What's Relevant

Instead of sending an entire knowledge base,

retrieve only the documents related to the user's question.

✅ Summarize Long Conversations

Rather than sending hundreds of previous messages,

summarize earlier parts while preserving important facts.

For example:

Instead of:

150 previous messages

Send:

Conversation Summary:

• User uses Go
• Building REST APIs
• Uses PostgreSQL
• Currently debugging authentication

Far fewer tokens.

Much easier for the model.

✅ Keep System Prompts Focused

System instructions should define behavior,

not contain an entire company handbook.

✅ Separate Long-Term Memory from Current Context

Store reusable preferences separately.

Retrieve them only when needed.

✅ Measure Token Usage

Don't optimize blindly.

Most AI SDKs expose token usage statistics.

Monitoring them helps identify unnecessary context and control costs.

🚫 Common Context Engineering Mistakes

Here are some patterns that often reduce AI quality rather than improve it.

❌ Dumping entire documents into every request

More information isn't automatically better.

❌ Sending the full conversation forever

Long conversations should be summarized or trimmed when appropriate.

❌ Treating memory as conversation history

They're different concepts.

❌ Ignoring token usage

Unexpected token growth often leads to higher costs and slower responses.

❌ Assuming bigger context windows solve everything

Context quality matters far more than context quantity.

🎯 Best Practices

If you're building AI-powered applications, keep these principles in mind:

✅ Send only the information required for the current task.

✅ Prefer relevant context over larger context.

✅ Separate memory from conversation history.

✅ Summarize older interactions instead of continuously expanding prompts.

✅ Monitor token usage in production.

✅ Design context deliberately instead of simply appending more text.

🏁 Final Thoughts

When people first start working with AI, they often focus on prompts.

Then they discover Context Engineering.

Eventually, they realize another important truth:

Not all context is equally valuable.

Modern AI systems succeed because they carefully decide:

What to include
What to exclude
What to summarize
What to retrieve
What to remember

That decision-making process is often more important than the prompt itself.

The best AI applications aren't the ones with the biggest context windows.

They're the ones that provide the right information at the right time.

And that's exactly what Context Engineering is about.

📌 Key Takeaways

Tokens are the fundamental units processed by language models—they are not the same as words.
Every request consumes tokens, including system prompts, conversation history, retrieved documents, tool outputs and the model's response.
A context window defines how much information a model can consider at once.
Larger context windows are useful, but more context doesn't automatically lead to better answers.
Context and memory are different: context exists for the current request, while memory is information intentionally stored and reintroduced by the application.
Effective Context Engineering is about sending relevant information, not all available information.
Good context management improves response quality, reduces costs and lowers latency.

🚀 Coming Up in Part 3

So far, we've answered:

What is Context Engineering?
What are tokens?
How do context windows work?
Why isn't bigger context always better?
What's the difference between context and memory?

But another important question remains:

Where does all this context actually come from?

How do AI applications automatically search documentation, query databases, call APIs, execute tools and decide what information should be sent to the model?

That's where concepts like Retrieval-Augmented Generation (RAG), Tool Calling, Model Context Protocol (MCP) and AI Agents come into the picture.

We'll break each of them down in Part 3 with practical examples and real-world engineering scenarios.

🧠 AI Context Engineering (Part 1): Why Great AI Systems Need More Than Great Prompts

Fazal Mansuri — Sat, 27 Jun 2026 11:15:39 +0000

A couple of years ago, almost every AI discussion revolved around one thing:

Prompt Engineering.

People shared prompts like:

"Use this prompt to become a senior software engineer."
"Use this prompt to write perfect SQL."
"Use this prompt to generate production-ready code."

The assumption was simple:

Better prompt = Better AI output.

While prompts certainly matter, engineers building production AI systems quickly realized something important:

The prompt is only one piece of the puzzle.

Modern AI applications - whether it's ChatGPT, Claude, Cursor, GitHub Copilot or AI coding agents - don't rely on a single prompt.

They combine multiple sources of information before generating a response.

That broader discipline is known as Context Engineering.

And understanding it is becoming one of the most valuable skills for engineers building AI-powered products.

What Is Context Engineering?

Context Engineering is the practice of providing an AI model with the right information at the right time so it can generate accurate, relevant, and reliable responses.

Think of it this way:

Prompt Engineering asks:

"What should I ask the model?"

Context Engineering asks:

"What information should the model have before it answers?"

That difference might sound subtle.

In reality, it changes everything.

A Simple Analogy

Imagine you ask two developers the same question.

"How do I fix this production bug?"

Developer A

You only tell them:

"The application is broken."

Can they help?

Maybe.

But they'll probably ask dozens of follow-up questions.

Developer B

Instead, you provide:

Error logs
Stack trace
API request
Database query
Recent deployment
Service architecture

Now they're much more likely to identify the issue quickly.

Did they become smarter?

No.

You simply gave them better context.

Large Language Models work the same way.

Prompt vs Context

Suppose you ask an AI:

Write a SQL query to fetch active users.

That's a perfectly valid prompt.

But now imagine providing additional context:

Database: PostgreSQL

Tables:

users
- id
- email
- status
- created_at

Status can be:
ACTIVE
INACTIVE
BLOCKED

Return only active users created after January 1st, 2025.

The prompt itself barely changed.

What improved was the context.

And naturally, the quality of the output improves as well.

Why Prompt Engineering Alone Isn't Enough

Imagine building an AI customer support assistant.

If every user message is handled using only:

User:
Where is my order?

the model has no idea:

Which customer is asking
Which order they mean
Whether it has already been shipped
Previous conversations
Company refund policy

Without that information, the model can only guess.

Instead, production AI systems enrich the request with additional context before sending it to the model.

For example:

System Instructions

Customer Name

Previous Conversation

Order Status

Shipping Details

Refund Policy

Current User Question

The model now has everything it needs to generate a useful answer.

Notice something interesting:

The user's prompt didn't become dramatically better.

The available context did.

What Actually Forms the Context?

Many developers think context means:

"The text I type into ChatGPT."

That's only part of it.

In reality, the model usually receives much more information.

A typical request may include:

System instructions
User prompt
Conversation history
Retrieved documentation
Project files
Tool outputs
Function call results
Memory from previous interactions

All of this together forms the context.

The model doesn't distinguish whether information came from you, a database, or another tool.

It simply processes the complete context it receives.

A Real-World Example

Consider an AI coding assistant.

You ask:

Explain this function.

How does it know which function you're referring to?

It doesn't.

The IDE silently provides additional context such as:

The currently opened file
Surrounding code
Project structure
Imported packages
Programming language
Cursor position

You only typed four words.

Yet the model received thousands of tokens of additional information behind the scenes.

That's Context Engineering in action.

Another Example: ChatGPT

Suppose you ask:

Summarize this document.

What actually reaches the model?

Something closer to:

System Instructions

Conversation History

Uploaded PDF

User Prompt

Formatting Rules

Safety Instructions

Again, the prompt is only a small part of the overall request.

The Mental Shift

Many developers spend hours refining prompts like:

Act as a senior software engineer with 20 years of experience...

Sometimes it helps.

But often, providing the model with:

Better documentation
Relevant code
Correct API schemas
Business rules
Examples

produces significantly better results than endlessly tweaking the wording of the prompt.

The question changes from:

"How should I ask?"

to:

"What information is the model missing?"

That's the mindset of Context Engineering.

Common Misconceptions

❌ "A bigger prompt always gives better answers."

Not necessarily.

Adding irrelevant information can confuse the model.

Good context is relevant, accurate, and focused.

❌ "Prompt Engineering is no longer useful."

Prompt Engineering is still important.

A clear prompt helps the model understand the task.

Context Engineering simply expands the scope by ensuring the model also has the information required to perform that task well.

Think of prompt engineering as one part of the larger Context Engineering process.

❌ "Only AI engineers need to know this."

If you build software that integrates AI in any form—chatbots, coding assistants, document search, customer support, or internal tools—understanding how context influences responses will help you design more reliable systems.

Why This Matters More Than Ever

Modern AI applications are no longer just chat interfaces.

They're becoming agents that:

Read documents
Search knowledge bases
Execute tools
Call APIs
Generate code
Reason over project files

The quality of these systems depends less on writing a "magic prompt" and more on giving the model the right context.

And that's exactly what Context Engineering is about.

What's Coming in Part 2?

Now that we understand why context matters, another important question arises:

How much context should we provide?

Is more always better?

What are tokens?

What is a context window?

Why do AI tools sometimes forget earlier parts of a conversation?

And why can adding too much information actually reduce response quality?

We'll answer all of these in Part 2, where we'll explore:

Context Windows
Tokens
Conversation History
Memory
Why bigger context isn't always better
Practical strategies used by modern AI applications

Understanding these concepts will completely change how you think about interacting with—and building—AI systems.

Key Takeaways

Prompt Engineering and Context Engineering are related, but not the same.
Great AI systems rely on much more than the user's prompt.
Context includes system instructions, conversation history, retrieved information, tool outputs, and more.
Better context often improves AI responses more than endlessly refining prompts.
Thinking in terms of "What information is the model missing?" is the first step toward building effective AI-powered applications.

If you've ever wondered why the same prompt produces excellent results in one AI application and poor results in another, the answer often isn't the model itself.

It's the context behind the scenes.

See you in Part 2 👋

🚨 CSS Specificity — The Hidden Reason Your UI Breaks

Fazal Mansuri — Sat, 06 Jun 2026 06:57:43 +0000

Most developers learn CSS specificity once.

They remember:

#id > .class > div

Then move on.

Until one day…

Everything looks correct.

The CSS is present.

The selector is correct.

The z-index looks higher.

And yet the UI is broken.

That’s when CSS specificity stops being a beginner topic and becomes a production debugging problem.

The Production Incident That Started This

Recently, I was working on a microfrontend application.

Everything worked fine initially.

I opened a page, launched a modal and the UI looked correct.

Then I navigated to another microfrontend.

Its CSS got loaded.

After returning to the original microfrontend, suddenly:

❌ Modal appeared behind page content
❌ Overlay behaved incorrectly
❌ z-index looked correct but wasn't working

DevTools showed my CSS rule still existed.

Yet another CSS rule was winning.

The culprit?

CSS Specificity.

🧠 What is CSS Specificity?

CSS specificity is the algorithm browsers use to decide:

Which CSS rule wins when multiple rules target the same element.

Browsers don't simply apply:

"The last CSS rule."

That's one of the biggest misconceptions.

Specificity is calculated first.

Only when specificity is equal does source order become important.

⚔️ Example

.modal {
  z-index: 9999;
}

.some-library .modal {
  z-index: 100;
}

HTML:

<div class="some-library">
  <div class="modal"></div>
</div>

Many developers expect:

.modal

to win because the value is larger.

But CSS doesn't compare values first.

It compares selectors.

🧮 How Specificity Works

Specificity is usually represented as:

ID - CLASS - TYPE

Specificity Table

Selector	Specificity
`*`	0-0-0
`div`	0-0-1
`.modal`	0-1-0
`[type="text"]`	0-1-0
`:hover`	0-1-0
`#dialog`	1-0-0
Inline Style	Highest

MDN defines specificity as the weight browsers calculate to determine which declaration gets applied when multiple selectors match the same element.

Example Calculation

Selector:

button.primary

Contains:

button     → 0-0-1
.primary   → 0-1-0

Total:

0-1-1

Another selector:

#header button.primary

Contains:

#header   → 1-0-0
button    → 0-0-1
.primary  → 0-1-0

Total:

1-1-1

This selector wins.

❌ Myth #1 — Last CSS Always Wins

Many developers believe:

The CSS rule written last wins.

Not always.

Example:

#header {
  color: red;
}

div {
  color: blue;
}

HTML:

<div id="header">
  Hello
</div>

Result:

Red

Why?

Because:

#header = 1-0-0
div     = 0-0-1

Specificity wins before source order.

❌ Myth #2 — Higher z-index Always Wins

This causes countless production bugs.

Developers often write:

.modal {
  z-index: 99999;
}

And expect it to appear above everything.

Not necessarily.

Because:

z-index works inside stacking contexts.

🧠 What is a Stacking Context?

A stacking context is a separate layering environment.

Example:

.parent {
  position: relative;
  z-index: 1;
}

.child {
  position: absolute;
  z-index: 999999;
}

Even with:

the child cannot escape its parent's stacking context.

This is why modal, tooltip, dropdown, and popover bugs often feel confusing.

The Microfrontend Problem

This is where specificity becomes extremely important.

Imagine:

Microfrontend A

.modal {
  z-index: 9999;
}

Microfrontend B

.layout .modal {
  z-index: 100;
}

Specificity:

.modal
0-1-0

.layout .modal
0-2-0

Microfrontend B wins.

Even if your CSS is still loaded.

Why My Fix Worked

Originally:

.modal {
  z-index: 9999;
}

But another selector had higher specificity.

So I wrapped the modal:

<div class="dialog-wrapper">
  <Modal />
</div>

Then:

.dialog-wrapper .modal {
  z-index: 9999;
}

Before:

.modal
0-1-0

After:

.dialog-wrapper .modal
0-2-0

Now my selector became more specific and started winning.

The CSS value never changed.

Only specificity changed.

And the issue disappeared.

🚨 Why This Happens More in Microfrontends

Microfrontends often share:

Same DOM
Same global CSS
Same class names
Same browser environment

Problems include:

CSS leakage
Style collisions
Unexpected overrides
Load-order changes after navigation

This makes specificity bugs significantly more common.

Modern CSS Specificity Features Developers Often Miss

1️⃣ `:is()`

Example:

:is(.btn, .link)

The :is() pseudo-class itself doesn't add specificity.

Instead, it takes the specificity of the most specific selector inside it.

Example:

:is(.btn, #header)

Specificity:

1-0-0

Because:

#header

is most specific.

2️⃣ `:not()`

Many developers think:

:not(.hidden)

adds nothing.

Not true.

:not() itself doesn't contribute specificity.

But selectors inside it do.

Example:

:not(.hidden)

Specificity:

0-1-0

3️⃣ `:where()`

One of the most underrated CSS features.

Example:

:where(.btn)

Specificity:

0-0-0

Always.

:where() intentionally has zero specificity.

This makes it extremely useful for:

Design systems
Component libraries
Shared UI frameworks

Because consumers can easily override styles.

How to Debug CSS Specificity Issues

When CSS isn't applying:

Check these in order:

1. Is the rule present?

Open DevTools.

Verify the CSS exists.

2. Is it crossed out?

Crossed-out CSS usually means:

Another rule won.

3. Which selector is winning?

DevTools shows the winning selector.

Inspect it carefully.

4. Compare specificity

Many bugs become obvious here.

5. Check CSS load order

When specificity is equal:

Last rule wins.

6. Check stacking contexts

Especially for:

Modals
Dropdowns
Tooltips
Popovers

7. Check portals

React portals often render outside expected DOM hierarchy.

This changes how CSS behaves.

🎯 Best Practices

✅ Prefer class selectors over IDs

✅ Avoid deeply nested selectors

✅ Use low-specificity CSS in shared libraries

✅ Use :where() for easily overridable styles

✅ Be careful with global CSS in microfrontends

✅ Avoid excessive !important

Final Thoughts

Most developers think CSS specificity is a beginner topic.

In reality:

It's one of the most common reasons production UIs break unexpectedly.

Especially in:

Large applications
Design systems
Microfrontends
Shared component libraries

The tricky part is that the CSS often looks correct.

The rule exists.

The value is correct.

And yet another selector silently wins.

Understanding specificity deeply transforms CSS debugging from:

Trial and Error

into:

Predictable Engineering

Key Takeaways

CSS does not simply apply the last rule
Specificity determines which selector wins
Higher z-index does not always mean higher visibility
Microfrontends make specificity issues more common
:is(), :not(), and :where() have special specificity behavior
!important should be a last resort
DevTools can quickly reveal specificity conflicts when used correctly

Understanding CSS specificity is one of those skills that feels minor — until it saves you hours of debugging a production UI issue.

API Pagination - Offset vs Cursor Pagination Explained

Fazal Mansuri — Sat, 16 May 2026 10:42:41 +0000

Most APIs don’t return all records at once.

Imagine:

Millions of users
Thousands of orders
Endless social media posts

Returning everything in a single response would:

Consume huge memory
Slow down queries
Increase network payload
Crash clients

That’s why APIs use:

Pagination

But here’s where many developers make mistakes:

Not all pagination strategies are equal.

The two most common approaches are:

Offset Pagination
Cursor Pagination

And choosing the wrong one can create:

Slow APIs
Duplicate records
Missing data
Poor user experience

Let’s understand everything properly.

🧠 What is Pagination?

Pagination means:

Splitting large datasets into smaller chunks (pages).

Instead of:

GET /posts

You request:

GET /posts?page=1&limit=10

This improves:

Performance
Scalability
User experience

📦 Offset Pagination

Offset pagination is the most common approach.

Example:

GET /posts?offset=20&limit=10

Meaning:

Skip first 20 rows
Return next 10 rows

⚙️ SQL Behind It

SELECT * FROM posts
ORDER BY id
LIMIT 10 OFFSET 20;

Simple Go Example - Offset Pagination

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "strconv"
)

type Post struct {
    ID    int    `json:"id"`
    Title string `json:"title"`
}

var posts []Post

func init() {
    for i := 1; i <= 100; i++ {
        posts = append(posts, Post{
            ID:    i,
            Title: "Post " + strconv.Itoa(i),
        })
    }
}

func getPosts(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query()

    offset, _ := strconv.Atoi(query.Get("offset"))
    limit, _ := strconv.Atoi(query.Get("limit"))

    if limit == 0 {
        limit = 10
    }

    end := offset + limit

    if offset > len(posts) {
        offset = len(posts)
    }

    if end > len(posts) {
        end = len(posts)
    }

    result := posts[offset:end]

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}

func main() {
    http.HandleFunc("/posts", getPosts)

    log.Println("Server running on http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

▶️ Run It

go run offset-pagination.go

📡 API Call

curl "http://localhost:8080/posts?offset=20&limit=5"

📦 Response

[
  {
    "id": 21,
    "title": "Post 21"
  },
  {
    "id": 22,
    "title": "Post 22"
  },
  {
    "id": 23,
    "title": "Post 23"
  },
  {
    "id": 24,
    "title": "Post 24"
  },
  {
    "id": 25,
    "title": "Post 25"
  }
]

✅ Advantages of Offset Pagination

Simple to implement
Easy to understand
Supports random page access

Example:

?page=50

❌ Problems with Offset Pagination

This is where things become interesting.

⚠️ Problem 1 — Slow Queries at Scale

Imagine:

LIMIT 10 OFFSET 1000000

Database still scans and skips 1 million rows.

💥 Very expensive.

⚠️ Problem 2 — Duplicate / Missing Records

Suppose user loads:

Page 1

Meanwhile:

New rows inserted
Old rows deleted

Now user loads:

Page 2

Result:

Duplicate rows
Missing rows

📉 Visual Problem

Before:

1 2 3 4 5 6 7 8 9 10

User fetches:
OFFSET 0 LIMIT 5

Gets:
1 2 3 4 5

Now new record inserted at top:

0 1 2 3 4 5 6 7 8 9 10

User fetches:
OFFSET 5 LIMIT 5

Gets:
5 6 7 8 9

⚠️ Duplicate "5"

🚀 Cursor Pagination

Cursor pagination solves these problems.

Instead of:

Skipping rows

We say:

Give records AFTER this specific item.

Example:

GET /posts?cursor=20&limit=10

Meaning:

Give next 10 posts after ID 20

⚙️ SQL Behind It

SELECT * FROM posts
WHERE id > 20
ORDER BY id
LIMIT 10;

Database uses index efficiently.

Simple Go Example — Cursor Pagination

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "strconv"
)

type Post struct {
    ID    int    `json:"id"`
    Title string `json:"title"`
}

var posts []Post

func init() {
    for i := 1; i <= 100; i++ {
        posts = append(posts, Post{
            ID:    i,
            Title: "Post " + strconv.Itoa(i),
        })
    }
}

func getPosts(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query()

    cursor, _ := strconv.Atoi(query.Get("cursor"))
    limit, _ := strconv.Atoi(query.Get("limit"))

    if limit == 0 {
        limit = 10
    }

    var result []Post

    for _, post := range posts {
        if post.ID > cursor {
            result = append(result, post)

            if len(result) == limit {
                break
            }
        }
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}

func main() {
    http.HandleFunc("/posts", getPosts)

    log.Println("Server running on http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

▶️ Run It

go run cursor-pagination.go

📡 API Call

curl "http://localhost:8080/posts?cursor=10&limit=5"

📦 Response

[
  {
    "id": 11,
    "title": "Post 11"
  },
  {
    "id": 12,
    "title": "Post 12"
  },
  {
    "id": 13,
    "title": "Post 13"
  },
  {
    "id": 14,
    "title": "Post 14"
  },
  {
    "id": 15,
    "title": "Post 15"
  }
]

✅ Advantages of Cursor Pagination

Fast for large datasets
Uses indexes efficiently
No duplicate/missing rows issue
Better for real-time systems

⚠️ Trade-Offs of Cursor Pagination

Not perfect either.

❌ No Random Page Access

You cannot easily jump to:

Page 50

Need sequential navigation.

❌ More Complex Implementation

Need:

Stable sorting
Unique cursor
Cursor encoding sometimes

🧠 What Companies Usually Do

🟢 Offset Pagination

Used for:

Admin panels
Internal dashboards
Small datasets

🟣 Cursor Pagination

Used for:

Social media feeds
Infinite scroll
Messaging apps
Large-scale APIs

🔥 Real-World Example

Instagram / Twitter Feed

Do you think they use:

OFFSET 5000000

❌ No chance.

They use cursor-based pagination.

⚡ Performance Difference

Offset Pagination

OFFSET 1000000

DB scans huge rows ❌

Cursor Pagination

WHERE id > 1000000

Direct index lookup ✅

🔐 Important Cursor Pagination Rule

Cursor field must be:

Indexed
Unique
Stable

Usually:

ID
Created timestamp

⚠️ Common Developer Mistakes

❌ Using OFFSET for infinite scroll

Bad at scale.

❌ Cursor based on non-unique column

Can create duplicates.

❌ Forgetting stable ordering

Pagination becomes inconsistent.

🧠 Key Mental Model

Offset Pagination

“Skip N rows”

Cursor Pagination

“Continue after this row”

📊 Quick Comparison

Feature	Offset Pagination	Cursor Pagination
Easy implementation	✅	❌
Random page access	✅	❌
Large dataset performance	❌	✅
Infinite scroll	❌	✅
Duplicate/missing record safety	❌	✅

🏁 Final Thoughts

Pagination seems simple.

But poor pagination strategy can:

Slow down APIs
Break user experience
Create inconsistent data

🎯 Key Takeaways

Offset pagination is simple but doesn’t scale well
Cursor pagination is efficient and production-friendly
Infinite scroll systems should prefer cursor pagination
Always use indexed & stable cursor fields

Good API design is not just about returning data.

It’s about returning data efficiently — even at massive scale.

GraphQL vs REST - Which One Should You Really Use?

Fazal Mansuri — Sun, 26 Apr 2026 07:04:52 +0000

For years, REST APIs have been the standard.

Then GraphQL came in with promises like:

“Fetch exactly what you need”
“Reduce API calls”
“More flexible APIs”

But here’s the reality:

GraphQL is not a replacement for REST.
It’s a different trade-off.

Let’s break it down — with real code you can run.

🧠 What is REST?

REST is a resource-based API design.

You expose endpoints like:

GET /users/1
GET /users/1/orders

Each endpoint returns fixed structure data.

⚙️ REST API — Fully Working Go Example

👉 Save as rest.go

package main

import (
    "encoding/json"
    "log"
    "net/http"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func getUserHandler(w http.ResponseWriter, r *http.Request) {
    user := User{
        ID:    1,
        Name:  "John",
        Email: "john@example.com",
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

func main() {
    http.HandleFunc("/users/1", getUserHandler)

    log.Println("REST server running on http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

▶️ Run it

go run rest.go

📡 Call API

curl http://localhost:8080/users/1

📦 Response

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

🧠 What is GraphQL?

GraphQL is a query-based API system.

Instead of multiple endpoints:

You use a single endpoint
Client decides what data it needs

⚙️ GraphQL API — Fully Working Go Example

👉 Save as graphql.go

Step 1: Install dependency

go mod init graphql-example
go get github.com/graphql-go/graphql

Step 2: Full working code

package main

import (
    "encoding/json"
    "log"
    "net/http"

    "github.com/graphql-go/graphql"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

var userData = User{
    ID:    1,
    Name:  "John",
    Email: "john@example.com",
}

func main() {

    // Define User type
    userType := graphql.NewObject(graphql.ObjectConfig{
        Name: "User",
        Fields: graphql.Fields{
            "id": &graphql.Field{
                Type: graphql.Int,
            },
            "name": &graphql.Field{
                Type: graphql.String,
            },
            "email": &graphql.Field{
                Type: graphql.String,
            },
        },
    })

    // Root query
    rootQuery := graphql.NewObject(graphql.ObjectConfig{
        Name: "Query",
        Fields: graphql.Fields{
            "user": &graphql.Field{
                Type: userType,
                Resolve: func(p graphql.ResolveParams) (interface{}, error) {
                    return userData, nil
                },
            },
        },
    })

    schema, err := graphql.NewSchema(graphql.SchemaConfig{
        Query: rootQuery,
    })
    if err != nil {
        log.Fatal(err)
    }

    // GraphQL handler
    http.HandleFunc("/graphql", func(w http.ResponseWriter, r *http.Request) {
        var params struct {
            Query string `json:"query"`
        }

        err := json.NewDecoder(r.Body).Decode(&params)
        if err != nil {
            http.Error(w, "invalid request body", http.StatusBadRequest)
            return
        }

        result := graphql.Do(graphql.Params{
            Schema:        schema,
            RequestString: params.Query,
        })

        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(result)
    })

    log.Println("GraphQL server running on http://localhost:8080/graphql")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

▶️ Run it

go run graphql.go

📡 Call API

curl -X POST http://localhost:8080/graphql \
-H "Content-Type: application/json" \
-d '{"query": "{ user { name email } }"}'

📦 Response

{
  "data": {
    "user": {
      "name": "John",
      "email": "john@example.com"
    }
  }
}

REST vs GraphQL — Visual Understanding

REST Flow

Client
  |
  |---- GET /users/1 ----------> Server
  |---- GET /users/1/orders ---> Server
  |---- GET /orders/101/items -> Server

Multiple requests ❌

GraphQL Flow

Client
  |
  |---- POST /graphql ---------> Server
        query {
          user {
            orders {
              items
            }
          }
        }

Single request ✅

⚠️ The Real Problem GraphQL Solves

REST Problem → Over-fetching

GET /users/1

Returns:

name, email, address, phone...

Even if you need only name.

REST Problem → Under-fetching

You need multiple calls to build UI.

GraphQL Solution

query {
  user {
    name
  }
}

👉 Exact data only.

⚖️ REST vs GraphQL — Honest Comparison

🧩 REST

✅ Simple
✅ Easy caching
✅ Easy debugging
❌ Multiple calls
❌ Over-fetching

🧩 GraphQL

✅ Flexible
✅ Single request
❌ Complex
❌ Hard caching

Note: REST uses native HTTP caching (like CDNs and browser headers), while GraphQL requires complex, custom caching strategies because queries are typically sent via POST.

❌ Query abuse risk

⚠️ Common Mistakes

❌ “GraphQL is always better”

No.

❌ Using GraphQL for simple CRUD

Overkill.

❌ Ignoring query complexity

Bad query:

users → posts → comments → replies → ...

💥 Performance issue

🧠 When to Use What

✅ Use REST when:

Simple APIs
CRUD operations
Strong caching needed
Easy debugging required

✅ Use GraphQL when:

Complex frontend
Aggregated data
Multiple services
Frequent UI changes

🔗 Real-World Architecture

Many companies use the GraphQL Gateway (or BFF) pattern:

Frontend → GraphQL Gateway → REST microservices

👉 GraphQL acts as an aggregation layer, allowing you to combine multiple REST responses into one, without refactoring the legacy backend.

🏁 Final Thoughts

GraphQL vs REST is not a battle.

It’s a design decision.

🎯 Key Takeaways:

REST = simple and predictable
GraphQL = flexible but complex
Both solve real problems
Choose based on use-case

🚀 Final Tip

If your API:

👉 Is simple → use REST
👉 Needs flexibility → use GraphQL

⚠️ Race Conditions in APIs - The Bug You Can’t See

Fazal Mansuri — Sat, 18 Apr 2026 09:02:13 +0000

There's a category of bugs that don't show up in tests. They don't throw errors. They don't crash your server. They just silently corrupt your data at the exact moment two users do the same thing at the same time.

That's a race condition.

And if you've ever seen a user's account balance go wrong, a product's stock count go negative, or a post get double-liked - you've seen one in production.

Let's break down exactly what's happening and how to fix it.

What Is a Race Condition?

A race condition happens when two concurrent operations read shared data, make a decision based on it, and write back — and neither knows the other exists.

The classic example:

Thread A reads stock = 10
Thread B reads stock = 10
Thread A writes stock = 9  (decremented by 1)
Thread B writes stock = 9  (also decremented from 10 — wrong!)

Two orders placed. One decrement applied. You just oversold your inventory.

The reason this is invisible: each individual operation is correct. Thread A did nothing wrong. Thread B did nothing wrong. The bug lives in the gap between the read and the write.

A Real Scenario: The Inventory API

Say you have an endpoint that handles a purchase:

// ❌ NOT safe under concurrent load
func purchaseItem(ctx context.Context, itemID string) error {
    var stock int
    err := db.QueryRow("SELECT stock FROM items WHERE id = $1", itemID).Scan(&stock)
    if err != nil {
        return err
    }

    if stock <= 0 {
        return errors.New("out of stock")
    }

    _, err = db.Exec("UPDATE items SET stock = $1 WHERE id = $2", stock-1, itemID)
    return err
}

This looks fine. In a single-user world, it is fine. But under load — say, a flash sale with 500 concurrent requests — the gap between SELECT and UPDATE is enough for dozens of threads to read the same stock value and all decrement from it simultaneously.

Result: Negative stock. Oversold orders. Angry customers.

Three Ways to Fix It

Fix 1 — Atomic SQL Update (the simplest approach)

The fastest fix is to eliminate the read-then-write pattern entirely and let the database handle the decrement atomically:

// ✅ Safe — single atomic statement
result, err := db.Exec(`
    UPDATE items
    SET stock = stock - 1
    WHERE id = $1 AND stock > 0
`, itemID)

rowsAffected, _ := result.RowsAffected()
if rowsAffected == 0 {
    return errors.New("out of stock or already taken")
}

No read. No gap. The database engine serializes this at the row level. This works well for simple decrements and is the right default when you don't need the old value.

Fix 2 — Pessimistic Locking (SELECT FOR UPDATE)

When you genuinely need to read the value before deciding what to write — for example, checking business rules before an update — use SELECT FOR UPDATE to hold a row lock:

// ✅ Safe — row is locked until transaction commits
tx, _ := db.BeginTx(ctx, nil)
// error handling omitted for brevity
defer tx.Rollback()

var stock int
err := tx.QueryRow(`
    SELECT stock FROM items WHERE id = $1 FOR UPDATE
`, itemID).Scan(&stock)

if stock <= 0 {
    return errors.New("out of stock")
}

tx.Exec("UPDATE items SET stock = $1 WHERE id = $2", stock-1, itemID)
tx.Commit()

FOR UPDATE tells the database: lock this row. Any other transaction that tries to read it with FOR UPDATE will block until this one commits or rolls back. Completely safe — but it creates a queue, so it can become a bottleneck under heavy concurrent traffic.

Fix 3 — Optimistic Locking with CAS (Compare-And-Swap)

Optimistic locking says: don't block anyone. Just verify before writing that the world still looks the way you expected when you read it.

You add a version column to the row, then make your update conditional:

// ✅ Safe — version mismatch causes retry, not corruption
type Item struct {
    ID      string
    Stock   int
    Version int
}

func purchaseWithCAS(ctx context.Context, itemID string) error {
    const maxRetries = 3

    for attempt := 0; attempt < maxRetries; attempt++ {
        var item Item
        db.QueryRow("SELECT id, stock, version FROM items WHERE id = $1", itemID).
            Scan(&item.ID, &item.Stock, &item.Version)

        if item.Stock <= 0 {
            return errors.New("out of stock")
        }

        result, _ := db.Exec(`
            UPDATE items
            SET stock = $1, version = $2
            WHERE id = $3 AND version = $4
        `, item.Stock-1, item.Version+1, item.ID, item.Version)

        rows, _ := result.RowsAffected()
        if rows == 1 {
            return nil // success
        }
        // version mismatch — someone else wrote first, retry
    }
    return errors.New("too many concurrent modifications, try again")
}

If two threads both read version=5, only the first one that writes version=6 wins. The second sees rowsAffected=0 and retries with a fresh read. No locks held, no blocking — just retry on conflict.

When to Use Which Fix

Scenario	Best approach
Simple increment/decrement	Atomic SQL (`UPDATE ... SET x = x - 1`)
Complex business logic before write	Pessimistic locking (`SELECT FOR UPDATE`)
High-read, low-conflict workloads	Optimistic locking (CAS + version)
Distributed systems / no shared DB	Distributed locks (Redis `SET NX`, etc.)

The Distributed Case: Redis to the Rescue

When your API runs across multiple servers and the database lock isn't enough (or too slow), you need a distributed lock. Redis handles this elegantly:

// ✅ Distributed lock using Redis SET NX (set if not exists)
func acquireLock(ctx context.Context, rdb *redis.Client, key string, ttl time.Duration) (bool, error) {
    ok, err := rdb.SetNX(ctx, "lock:"+key, "1", ttl).Result()
    return ok, err
}

func releaseLock(ctx context.Context, rdb *redis.Client, key string) {
    rdb.Del(ctx, "lock:"+key)
}

func purchaseWithRedisLock(ctx context.Context, rdb *redis.Client, db *sql.DB, itemID string) error {
    acquired, err := acquireLock(ctx, rdb, itemID, 5*time.Second)
    if err != nil || !acquired {
        return errors.New("could not acquire lock, try again")
    }
    defer releaseLock(ctx, rdb, itemID)

    // safe to read and write now — only one server can be here at a time
    return purchaseItem(ctx, db, itemID)
}

The SET NX command is atomic in Redis — only one caller gets true. All others get false and back off. The TTL ensures the lock is released even if your server crashes mid-operation.

⚠️ One important caveat: SET NX alone isn't enough for production. Use Redlock (Redis's official distributed locking algorithm) when you need strong guarantees — especially if you have multiple Redis nodes.

Summary: The Mental Model

Race conditions happen in the gap between read and write. The longer that gap, the higher the chance of corruption. Your goal is to shrink or eliminate that gap:

Atomic operations collapse the gap to zero.
Pessimistic locks block others from entering the gap.
Optimistic locks let everyone in but detect and reject stale writes.

There's no universally best answer. Pick the approach that matches your read/write ratio, your tolerance for blocking, and whether your system is distributed.

Key Takeaways

A race condition is not a bug in any single thread — it's a bug in timing between threads.
Any "read, decide, write" pattern is vulnerable unless protected.
The simplest fix is often a single atomic SQL statement — reach for it first.
SELECT FOR UPDATE is your safety net when you need business logic between the read and write.
Optimistic locking with a version column is ideal for high-concurrency, low-conflict scenarios.
In distributed systems, move to Redis-based locking.

Have you been bitten by a race condition in production? How did you track it down? Drop a comment - these bugs have some of the best war stories.

🚀 Feature Flags - The Secret Behind Safe Deployments

Fazal Mansuri — Sun, 15 Mar 2026 07:49:04 +0000

Shipping software used to be risky.

A new deployment could introduce bugs, break critical workflows or affect thousands (or millions) of users instantly.

For many teams, releasing software meant:

Deploying late at night 🌙
Monitoring dashboards anxiously 📊
Hoping nothing breaks 🤞

Modern engineering teams solved this problem using Feature Flags.

Feature flags allow developers to release code without immediately exposing new features to users.

Instead of deploying and hoping everything works, teams can control feature visibility dynamically.

🧠 What Are Feature Flags?

A Feature Flag (also called a Feature Toggle) is a mechanism that enables or disables functionality in an application without deploying new code.

In simple terms:

if feature_flag_enabled:
    show_new_feature()
else:
    use_old_behavior()

The application contains both code paths, but the feature flag decides which one runs.

This allows developers to separate deployment from release.

Key idea:

Deployment → Shipping code to production
Release → Making the feature available to users

Feature flags allow these two processes to happen independently.

🎯 Why Feature Flags Matter

Feature flags dramatically reduce the risk of releasing software.

Without Feature Flags

Deploy → Feature immediately live

If something breaks, the only option is rollback.

With Feature Flags

Deploy → Feature disabled → Enable gradually

If something goes wrong, simply turn the feature off.

No redeployment required.

Benefits of Feature Flags

Feature flags enable:

✅ Safer releases
✅ Gradual rollouts
✅ Instant rollback
✅ Production testing
✅ Controlled experiments

🛒 Real-World Example

Imagine launching a new checkout system for an e-commerce platform.

Without Feature Flags

Deploy new checkout → All users see it

If checkout fails → Revenue stops immediately 💥

With Feature Flags

Deploy new checkout → Feature disabled
Enable for 5% users
Monitor metrics
Gradually increase rollout

If problems appear, the feature can be disabled instantly.

🧩 Types of Feature Flags

Not all feature flags are used for the same purpose.

Understanding their types helps design systems properly.

1️⃣ Release Flags

Used to gradually release new features.

Example:

new_checkout_enabled

Purpose:

Control feature rollout
Reduce release risk

Release flags are usually temporary and removed once the feature is stable.

2️⃣ Experiment Flags (A/B Testing)

Used for product experiments.

Example:

checkout_variant_A
checkout_variant_B

Users may see different versions of a feature.

Metrics measured include:

📈 Conversion rate
📊 Engagement
🔁 Retention

3️⃣ Operational Flags

Used to control system behavior during incidents.

Example:

disable_recommendation_engine

If a system starts failing, the feature can be disabled instantly.

Operational flags are useful during production outages.

4️⃣ Permission Flags

Used to control access based on user roles.

Example:

admin_dashboard_enabled

Only certain users or roles see the feature.

This is commonly used for:

internal tools
beta programs
admin dashboards

⚙️ Feature Flags vs Configuration Flags

These concepts are often confused.

Feature Flags

Used to control product functionality.

Characteristics:

Temporary
Used for rollouts
Tied to releases

Example:

enable_new_upload_ui = true

Configuration Flags

Used to control system configuration.

Characteristics:

Usually permanent
Not tied to releases

Example:

max_upload_size = 20MB

Understanding this difference prevents misuse of feature flags.

🧪 Simple Implementation Example (Go)

Here is a simple feature flag example in Go:

type FeatureFlags struct {
    NewCheckout bool
}

func Checkout(flags FeatureFlags) {
    if flags.NewCheckout {
        newCheckoutFlow()
    } else {
        oldCheckoutFlow()
    }
}

Feature flag values may come from:

configuration files
environment variables
databases
remote config services

🌐 Remote Feature Flag Systems

In production, feature flags are often managed remotely.

Popular platforms include:

LaunchDarkly
Split
Flagsmith

These systems allow teams to:

toggle features instantly ⚡
target specific users 🎯
monitor rollout metrics 📊

No redeployment required.

📈 Gradual Rollouts

One of the most powerful capabilities of feature flags is progressive rollout.

Example rollout strategy:

1% users → monitor
10% users → monitor
50% users → monitor
100% users → full release

This dramatically reduces release risk.

Problems can be detected before the feature reaches everyone.

🎯 Targeted Rollouts

Feature flags can also target specific user segments.

Examples:

internal employees
beta testers
specific countries
premium users

Example logic:

if user.country == "US":
    enable_feature()

This enables testing directly in production environments.

🐤 Canary Releases

Feature flags are commonly used with canary releases.

A canary release exposes a feature to a small subset of users first.

This helps detect:

performance issues
unexpected errors
unusual user behavior

before rolling it out globally.

🌑 Dark Launching

Another advanced technique is Dark Launching.

The feature is deployed but hidden from users.

The system still runs the feature in the background to test performance.

Example:

recommendation_engine_running = true
recommendation_visible = false

This helps test infrastructure safely before exposing the feature.

⚠️ The Hidden Problem: Feature Flag Debt

Feature flags are powerful, but they introduce a new problem:

Feature Flag Debt

Over time, many flags remain in the codebase long after the feature is released.

Example:

if old_feature_flag:

But the feature is already permanent.

This leads to:

messy code
confusion
technical debt

Flags should be removed once they are no longer needed.

🚨 Common Mistakes With Feature Flags

Many teams misuse feature flags.

Here are common pitfalls.

1️⃣ Flag Explosion

Too many flags make systems difficult to understand.

Every flag increases system complexity.

2️⃣ Flags in Performance-Critical Paths

Checking flags in very hot paths may affect performance.

Flag evaluation should be fast and lightweight.

3️⃣ Long-Lived Release Flags

Release flags should be temporary.

Once rollout finishes, remove them.

4️⃣ Mixing Flags With Business Logic

Feature flags should control behavior, not implement complex logic.

Avoid deeply nested conditions like:

if flagA and not flagB and flagC

✅ Best Practices

Successful teams follow several important practices.

1️⃣ Treat Flags as Temporary

Every release flag should have an expiration plan.

2️⃣ Track Flag Ownership

Each flag should have an owner responsible for cleanup.

3️⃣ Monitor Feature Rollouts

Always observe metrics when enabling a feature.

Examples:

error rate
latency
user behavior

4️⃣ Use Clear Naming

Bad naming:

flag123

Better naming:

checkout_v2_release

Clear names improve maintainability.

5️⃣ Remove Flags After Release

Cleaning up unused flags keeps the codebase healthy.

⚡ Feature Flags Enable Modern DevOps

Feature flags are a key component of modern engineering practices.

They enable:

🚀 Continuous deployment
🧪 Safe experimentation
🔄 Instant rollbacks
🎯 Controlled feature releases

Instead of fearing deployments, teams can release features with confidence.

🏁 Final Thoughts

Feature flags fundamentally change how software is delivered.

They transform deployments from risky events into controlled experiments.

But like any powerful tool, they must be used carefully.

Without discipline, feature flags can create complexity and technical debt.

When implemented correctly, they become one of the most powerful tools in a developer’s toolbox.

DEV Community: Fazal Mansuri

🛠️ Database Connection Pooling: The Hidden Bottleneck That Can Bring Your Application Down

1. First, why do we need a database connection pool?

2. How connection pooling works in Go

3. Understanding the connection pool configuration

SetMaxOpenConns

SetMaxIdleConns

SetConnMaxLifetime

SetConnMaxIdleTime

Putting everything together

4. The real problem: How does an application run out of connections?

5. Common causes of connection leaks and pool exhaustion

Problem 1: Forgetting to close query rows

Problem 2: Not completing database transactions

Problem 3: Starting another database operation inside a transaction

Problem 4: Long-running queries

Problem 5: Queries without timeouts

6. Let's reproduce connection pool exhaustion

7. How to debug connection pool exhaustion in a real application

Step 1: Check pool statistics

Step 2: Check whether connections are being released

Step 3: Check the database server itself

Step 4: Check query latency and acquisition time separately

Step 5: Don't use application restarts as the permanent fix

8. How should you choose the connection pool size?

What factors should influence the pool size?

A practical approach

9. Best practices for production applications

1. Create one shared database pool

2. Always close query rows

3. Always complete transactions

4. Use context-aware database operations

5. Don't hold connections longer than necessary

6. Monitor pool statistics

7. Monitor the database too

8. Size pools across all application instances

9. Use query timeouts and appropriate indexes

10. Test under concurrency

10. A few misconceptions worth clearing up

11. Your production debugging checklist

Final thoughts

🧩 JavaScript Promises Inside Promises: The Hidden Bugs, Execution Flow and How to Fix Them

1. First, let's reproduce the bug

The buggy implementation

What JavaScript actually does

The fix: return the Promise

2. What is a Promise, really?

3. What happens when a Promise is inside another Promise?

Pattern A: Returning a Promise from another Promise

Pattern B: Creating a Promise but not returning it

A complete execution-order example

4. Nested .then() callbacks vs. Promise chaining

5. The missing return: a small mistake with several consequences

Case 1: The next step starts too early

Case 2: Errors don't propagate through the expected chain

Case 3: The caller receives a result too early

6. Is this bug specific to Promises, or does it also happen with async/await?

Incorrect async/await implementation

Correct implementation

A useful rule

7. Error handling: .catch() vs. try/catch

Promise-based error handling

The equivalent async/await approach

Should you always rethrow an error?

8. Promise vs. async/await: which should you use?

Scenario A: Sequential operations

Scenario B: Several independent operations

Scenario C: Independent operations where partial results matter

Scenario D: You want a Promise chain without an async function

A practical decision guide

9. One real-world decision: should the email block registration?

Option A: Email is part of the required workflow

Option B: Registration should succeed independently of email delivery

10. How to debug confusing Promise execution flow

Step 1: Add logs at the boundaries

Step 2: Inspect every asynchronous callback

Step 3: Inspect the returned value

Step 4: Check rejection paths, not just successful execution

Step 5: Write down the intended dependency

11. Common misconceptions worth remembering

`SetMaxOpenConns`

`SetMaxIdleConns`

`SetConnMaxLifetime`

`SetConnMaxIdleTime`

4. Nested `.then()` callbacks vs. Promise chaining

5. The missing `return`: a small mistake with several consequences

6. Is this bug specific to Promises, or does it also happen with `async/await`?

Incorrect `async/await` implementation

7. Error handling: `.catch()` vs. `try/catch`

The equivalent `async/await` approach

8. Promise vs. `async/await`: which should you use?

Scenario D: You want a Promise chain without an `async` function