Why are request-scoped providers slow in NestJS?

A provider marked Scope.REQUEST is created once per incoming request instead of once at startup. The cost spreads past that one class because scope in Nest bubbles up the injection chain. A singleton cannot hold a reference to something that exists only for one request, so every provider that injects a request-scoped dependency becomes request-scoped too. That includes the controller at the top. Injecting the REQUEST token has the same effect.

How the scope spreads

Take a typical tenant-aware graph:

  • TenantConnectionService is request-scoped because it reads the tenant ID from the request.
  • OrdersRepository injects it, so it becomes request-scoped.
  • OrdersService injects the repository, so it becomes request-scoped.
  • OrdersController injects the service, so it becomes request-scoped.

Scope only bubbles upward. A config or logger service that TenantConnectionService injects stays a singleton. Everything that depends on the tenant service, directly or indirectly, is rebuilt on every request. That means four constructors run, dependencies are resolved four times, and four objects are handed to the garbage collector afterwards. This happens on every route that touches orders. In real apps the chain is usually wider, because shared services pull in several repositories.

Finding it

Add a log line to the constructor of each suspect class. Singletons log once at bootstrap. Request-scoped classes log on every hit, and the lines that repeat show you the bubbled chain.

This matters most to teams running multi-tenant NestJS apps who made one tenant-resolving provider request-scoped and now pay to rebuild the whole graph on every request.

import { Controller, Get, Inject, Injectable, Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';

// The only class explicitly marked request-scoped: it needs the tenant header.
@Injectable({ scope: Scope.REQUEST })
export class TenantConnectionService {
  constructor(@Inject(REQUEST) private readonly req: Request) {
    console.log('TenantConnectionService constructed');
  }
  get tenantId(): string {
    return this.req.headers['x-tenant-id'] as string;
  }
}

// No scope option here, but injecting a request-scoped provider makes it request-scoped.
@Injectable()
export class OrdersRepository {
  constructor(private readonly tenant: TenantConnectionService) {
    console.log('OrdersRepository constructed');
  }
}

// Bubbled one level further up the chain.
@Injectable()
export class OrdersService {
  constructor(private readonly repo: OrdersRepository) {
    console.log('OrdersService constructed');
  }
}

// The controller is rebuilt per request too; this line repeating on every hit confirms the bubble.
@Controller('orders')
export class OrdersController {
  constructor(private readonly orders: OrdersService) {
    console.log('OrdersController constructed');
  }
  @Get()
  list() {
    return [];
  }
}

Constructor logs on a tenant-aware chain: only TenantConnectionService is marked Scope.REQUEST, but all four log lines repeat on every GET /orders, which shows the scope bubbling up to the controller.

Who should use durable providers?

Durable providers are aimed at a specific situation. You are a good fit if all of the following hold:

  • You run a multi-tenant NestJS service where each request belongs to exactly one tenant, and the tenant can be derived from trusted input such as a verified token claim or an allowlisted hostname.
  • You already rely on request scope for tenant data, and the constructor-logging check above shows the scope bubbling through repositories, services and controllers.
  • Per-tenant setup is non-trivial. Constructors or factories load tenant configuration, build API clients, or open database pools, so rebuilding them per request costs real work.
  • Each tenant sends repeated traffic. Durable instances only pay off from a tenant's second request onward, so a moderate number of reasonably active tenants benefits most.

You are probably not a fit if the app is single-tenant, if the request-scoped state is mostly per-request (current user, request ID, open transaction), or if you have a very large tail of tenants that each send only a handful of requests. Those cases are covered in more detail in the final section.

What are NestJS durable providers and how do they work?

Durable providers fix this by keying the subtree to the tenant instead of the request. You declare one with @Injectable({ scope: Scope.REQUEST, durable: true }). It is still request-scoped and still opted out of the singleton graph. The difference is which context ID Nest uses to look it up.

How it works at request time

On every request, Nest calls your ContextIdStrategy. For each request-scoped provider it must resolve, the strategy's resolver receives a HostComponentInfo and returns a context ID. info.isTreeDurable tells you whether that provider's dependency tree is durable:

  • Durable trees get a context ID shared by every request from the same tenant. Nest builds that subtree once and serves the cached instances to later requests.
  • Non-durable trees get the per-request context ID, so they are rebuilt every time.

Put together, the sequence for one request is:

  1. Nest creates a fresh per-request context ID.
  2. It calls your strategy's attach, which maps the request to a tenant and returns a resolver plus a payload.
  3. For each request-scoped provider in the route's graph, Nest asks the resolver which context ID to use.
  4. Durable providers are looked up under the tenant's context ID. If instances already exist there, Nest reuses them; otherwise it builds them and caches them under that ID.
  5. Non-durable providers are built under the per-request context ID and discarded when the request ends.

Durability follows the dependency graph. A provider is durable only if its request-scoped dependencies are durable too. A controller that injects both a durable tenant service and a per-request logger is non-durable, so it is rebuilt per request. When it is constructed, its durable dependency still resolves from the tenant's cached subtree. You pay only for the non-durable part.

Aspect Durable request-scoped Non-durable request-scoped
Lifetime Per context ID (e.g. tenant) Per request
Typical contents Tenant config, DB connection or client, feature flags Request-ID logger, current user, auth claims
What REQUEST injects Strategy payload (e.g. { tenantId }) Actual request object
Rebuild cost Once per tenant Every request

The REQUEST row is easy to miss. A durable instance outlives the request that created it, so it never sees a live request. It sees only the payload your strategy attached. Keep anything user- or request-specific out of durable providers.

How do you implement a ContextIdStrategy for tenants?

The strategy is a class implementing ContextIdStrategy with a single method, attach(contextId, request). Nest calls it for each incoming request and passes in the fresh per-request contextId it has already created. Your job is to decide which context each provider tree should resolve against.

Steps

  1. Derive the tenant key from verified input. Read the tenant from something you can trust, such as a verified token claim or a hostname matched against a known list. Normalize it to one canonical form by trimming, lowercasing, and validating it against an allowlist pattern. Without that, Acme and acme produce two separate sets of durable instances.
  2. Look up a stable ContextId. Keep a module-level Map from tenant key to a ContextId. On a miss, create one with ContextIdFactory.create() and store it. Every request for that tenant then shares the same durable subtree. The map grows with the number of tenants, so plan to bound it. Eviction is covered in the testing and eviction section below.
  3. Return a resolver and a payload. Return an object with resolve and payload:
    • resolve receives info and returns the tenant ContextId when info.isTreeDurable is true. Otherwise it returns the per-request contextId.
    • payload, for example { tenantId }, is what durable providers receive when they inject REQUEST. They do not receive the live request object.
  4. Register globally. Call ContextIdFactory.apply(new TenantContextIdStrategy()) during bootstrap, before the app starts listening.

The security boundary

attach can run before your guards do. If it trusts a raw X-Tenant-Id header, a caller can spoof that header and bind to another tenant's cached providers, including their connections and configuration. Never fall back to a default tenant when the key is missing or invalid. Instead, route the request to a non-durable context or reject it outright.

import { ContextId, ContextIdFactory, ContextIdStrategy, HostComponentInfo } from '@nestjs/core';
import { Request } from 'express';

// Tenants are matched against a known list, not taken from a client-supplied header.
const KNOWN_TENANTS = new Set(['acme', 'globex', 'initech']);
const TENANT_PATTERN = /^[a-z0-9-]{1,32}$/;

// One stable ContextId per tenant. Bound or evict this map in production.
const tenants = new Map<string, ContextId>();

function resolveTenant(request: Request): string | undefined {
  // Use the subdomain of the hostname, e.g. acme.app.example.com, as the tenant key.
  const raw = (request.hostname ?? '').split('.')[0];
  const key = raw.trim().toLowerCase(); // one canonical form, so 'Acme' and 'acme' match
  if (!TENANT_PATTERN.test(key) || !KNOWN_TENANTS.has(key)) return undefined;
  return key;
}

export class TenantContextIdStrategy implements ContextIdStrategy {
  attach(contextId: ContextId, request: Request) {
    const tenantId = resolveTenant(request);
    // No default tenant fallback. Without a tenant, nothing durable is shared,
    // and a guard later rejects the request.
    if (!tenantId) return undefined;

    let tenantContextId = tenants.get(tenantId);
    if (!tenantContextId) {
      tenantContextId = ContextIdFactory.create();
      tenants.set(tenantId, tenantContextId);
    }

    return {
      // Durable trees share the tenant context. Everything else stays per request.
      resolve: (info: HostComponentInfo) => (info.isTreeDurable ? tenantContextId : contextId),
      // Durable providers that inject REQUEST receive this object, not the live request.
      payload: { tenantId },
    };
  }
}

// main.ts, before app.listen():  ContextIdFactory.apply(new TenantContextIdStrategy());

A tenant ContextIdStrategy that normalizes and allowlists the tenant key from the hostname, caches one ContextId per tenant, routes durable trees to it, and passes { tenantId } as the REQUEST payload.

Which tenant resources belong in durable providers?

Durable subtrees fit resources that are expensive to build, identical for every request from the same tenant, and safe to share concurrently. Three categories cover most cases:

  • Per-tenant database connections or pools. Building a pool means a TCP handshake, TLS, and authentication. A durable provider pays that cost once per tenant instead of once per request.
  • Tenant configuration and feature flags. Load these once and treat them as read-only. If flags must change at runtime, refresh them by replacing the whole object rather than mutating fields in place.
  • Per-tenant API clients. These are clients bound to tenant-specific credentials, base URLs, or rate-limit budgets.

The rule that keeps this safe is that a durable instance is shared by every concurrent request for that tenant. Never store the current user, an open transaction, a cursor, or any other per-request value on it. If two requests interleave across an await, one request will read the other's state. That data stays in a non-durable, request-scoped provider or is passed as an argument.

Be careful with lifecycle hooks. Module-level init and destroy hooks are not invoked for request-scoped providers, so do initialization in an async factory. Teardown must be explicit: when you evict a tenant, close its pool yourself, or the connections will leak.

Connection counts multiply across tenants and instances. As an illustrative estimate, 50 tenants × a pool size of 10 × 4 replicas comes to 2,000 potential connections. Keep per-tenant pools small, cap the number of cached tenants, and check the total against your database's connection limit.

import { Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Pool } from 'pg';

export const TENANT_POOL = Symbol('TENANT_POOL');
const MAX_CACHED_TENANTS = 50; // keep tenants x max x replicas under the DB connection limit
const pools = new Map<string, Pool>();

// Durable factory: runs once per tenant subtree, not once per request.
// Module init/destroy hooks don't fire for request-scoped providers, so setup happens here.
export const tenantPoolProvider = {
  provide: TENANT_POOL,
  scope: Scope.REQUEST,
  durable: true,
  inject: [REQUEST], // for durable trees this is the payload from ContextIdStrategy, e.g. { tenantId }
  useFactory: async ({ tenantId }: { tenantId: string }) => {
    if (pools.size >= MAX_CACHED_TENANTS && !pools.has(tenantId)) {
      throw new Error('Tenant pool cache is full; evict a tenant first');
    }
    const pool = pools.get(tenantId) ?? new Pool({
      connectionString: `postgres://app:example-password@db.internal:5432/tenant_${tenantId}`,
      max: 5, // small per-tenant pool
    });
    pools.set(tenantId, pool);
    // Return only shared, read-only state. Never attach the current user,
    // a transaction, or a cursor here: concurrent requests share this instance.
    return pool;
  },
};

// Teardown is explicit: close the pool when a tenant is evicted, or its
// connections leak. Also drop the tenant's cached ContextId in your
// ContextIdStrategy so the next request builds a fresh durable subtree.
export async function evictTenantPool(tenantId: string): Promise<void> {
  const pool = pools.get(tenantId);
  if (!pool) return;
  pools.delete(tenantId);
  await pool.end();
}

A durable, request-scoped factory provider builds a small per-tenant Postgres pool once per tenant inside an async factory, caps how many tenants are cached, and closes the pool explicitly when the tenant is evicted.

How much do durable providers save? An illustrative estimate

Illustrative estimate (assumed numbers, not a benchmark). Assume one replica handles 500 requests per second, the request-scoped subtree contains 8 providers, and traffic comes from 50 tenants.

  • Request-scoped: instantiations per second = RPS × P = 500 × 8 = 4,000
  • Durable: total instantiations = T × P = 50 × 8 = 400, paid once per tenant subtree and repeated only after eviction or restart
Scenario Request-scoped Durable
Steady state, all 50 tenants active 4,000 per second, indefinitely 0 per second after warm-up
A tenant's first request 8 instantiations 8 instantiations (same cold start)
Tenant sending 1 request per hour, evicted between requests 8 per request 8 per request, plus cached memory while it lives

The first request for each tenant costs the same under both models, because durability only helps from the second request onward. Gains therefore come from tenants with many requests per subtree lifetime. A long tail of rarely active tenants gets little benefit. If your eviction policy drops those tenants before their next request, you pay the cold start every time and still hold memory between requests.

A count of instantiations is not a measure of latency. If the constructors only assign fields, 4,000 small allocations per second may not appear in a profile at all. The savings matter when constructors parse tenant configuration, build clients, or open connections. Profile your own constructors under realistic traffic before you decide.

Then weigh that result against what the change costs to build and maintain: a context ID strategy, eviction logic, connection budgeting, and tests for cross-tenant leakage. Spend that engineering time only where profiling shows request-scoped construction on the hot path.

How can durable providers save engineering time?

The runtime savings above are only part of the picture. The other benefit is how little of the existing code has to change to get them.

  • No signature refactor. The usual alternative to request scope is to pass the tenant ID explicitly through every controller, service and repository method. In a large codebase that touches many files and creates merge conflicts with ongoing work. With durable providers, services keep injecting TenantConnectionService or a tenant pool exactly as before. The main changes are a durable: true flag on the right providers and one strategy class.
  • Tenant resolution lives in one place. Normalization, allowlisting and the "no default tenant" rule sit in attach. When the way tenants are identified changes, for example moving from subdomains to a token claim, you edit one function instead of auditing every place that reads a header.
  • Per-tenant setup is written once. Pool creation, client construction and config loading live in durable factories. Feature code asks for a ready-made dependency and does not need to know about caching.
  • Fewer ad-hoc caches. Without durable providers, teams often add hand-rolled module-level maps of tenant clients inside individual services, each with its own eviction rules and bugs. A single durable subtree per tenant replaces those with one mechanism and one eviction path.
  • Regressions are testable. The identity tests in the next section turn "someone accidentally made this per-request again" into a failing test rather than a performance investigation in production.

The time you save is offset by work you take on: writing and reviewing the strategy, building eviction and teardown, budgeting connections, and maintaining cross-tenant isolation tests. For an app that already uses request-scoped tenant providers, that is usually a smaller, more contained change than rewriting call signatures. For an app with no tenant state in DI, it may not be.

How do you test and debug durable providers and tenant eviction?

Testing durable providers starts with obtaining a context ID the same way Nest does at runtime. Build a fake request object carrying the tenant identifier. Apply your strategy with ContextIdFactory.apply(), derive a context ID from the fake request with ContextIdFactory.getByRequest(), and pass it to moduleRef.resolve(TenantService, contextId). Repeat with a second request object for the same tenant and assert strict identity (toBe, not toEqual). Then do the same for a different tenant and assert the instances differ. The cross-tenant assertion matters more than the reuse assertion, because a strategy bug that collapses tenants into one subtree leaks data rather than merely wasting memory.

Eviction is your job

Nest never evicts a tenant subtree. The strategy's map of tenant context IDs only grows, and every entry pins its instances along with any pools, sockets or caches they hold. Put the map behind an LRU or TTL policy. When an entry is evicted, close its resources explicitly. Do not rely on lifecycle hooks, because Nest does not run shutdown hooks for request-scoped instances. Verify in your own setup that dropping a context ID actually frees its instances. One way is to hold a WeakRef to a resolved instance, evict the tenant, and force collection under node --expose-gc. Another is to compare heap snapshots before and after a tenant churn test.

Catching accidental bubbling

If someone adds a non-durable request-scoped dependency anywhere in the chain, every provider above it silently becomes per-request again. Add a regression test that resolves your top-level tenant consumers twice for one tenant and asserts identity. In load tests, count constructor invocations and fail the run if the count exceeds the number of tenants.

import { Test, TestingModule } from '@nestjs/testing';
import { ContextIdFactory } from '@nestjs/core';
import { TenantModule } from './tenant.module';
import { TenantService } from './tenant.service';
import { TenantContextStrategy } from './tenant-context.strategy';

// Minimal fake request: only what the strategy reads.
const fakeRequest = (tenantId: string) => ({ headers: { 'x-tenant-id': tenantId } });

describe('durable TenantService', () => {
  let moduleRef: TestingModule;

  beforeAll(async () => {
    // Apply the same strategy the app uses at runtime.
    ContextIdFactory.apply(new TenantContextStrategy());
    moduleRef = await Test.createTestingModule({ imports: [TenantModule] }).compile();
  });

  // Derive the context ID exactly as Nest does for an incoming request.
  const resolveFor = (tenantId: string) => {
    const contextId = ContextIdFactory.getByRequest(fakeRequest(tenantId));
    return moduleRef.resolve(TenantService, contextId, { strict: false });
  };

  it('reuses one instance per tenant (fails if a dependency bubbles to per-request)', async () => {
    const first = await resolveFor('acme');
    const second = await resolveFor('acme');
    expect(second).toBe(first); // identity, not structural equality
  });

  it('isolates tenants from each other', async () => {
    const acme = await resolveFor('acme');
    const globex = await resolveFor('globex');
    expect(globex).not.toBe(acme); // a collapse here would leak data
  });

  afterAll(() => moduleRef.close());
});

A Jest test that applies the tenant strategy, derives context IDs from fake requests with ContextIdFactory.getByRequest(), and resolves TenantService through ModuleRef.resolve() to assert same-tenant reuse and cross-tenant isolation.

When should you avoid durable providers, and what are the alternatives?

Constructor counts only help if durable providers were the right choice. In three common cases they are not.

The first is when most of your request-scoped providers are genuinely per-request. Request IDs, the authenticated user, and per-request transactions cannot be shared across a tenant. Making their parents durable still leaves them request-scoped, so the scope bubbles back up and you add strategy code without removing per-request instantiation.

The second is a large tenant population with low activity per tenant. Durable subtrees stay cached until you evict them. With thousands of tenants that each send a few requests a day, the cache hit rate is low and memory grows with the number of tenants ever seen, not the number currently active.

The third is when the only per-tenant data is an identifier. Building a provider subtree just to hold a string costs more than it saves.

In these cases, keep providers singleton and move the tenant out of the DI graph:

Approach Provider scope Safety Maintenance cost Best fit
Durable providers Per tenant Strong isolation of cached state Strategy, eviction, identity tests Expensive per-tenant clients or config
AsyncLocalStorage Singleton Context can be lost in callbacks registered outside the request Middleware setup; tests must run inside a context Tenant ID needed deep in many call paths
Explicit parameter Singleton Compiler-checked, no hidden state Signature churn across layers Shallow call graphs, domain services

AsyncLocalStorage keeps call signatures clean, but every consumer depends on state it cannot see in its signature. Explicit passing is noisier to write, but nothing about it can silently break. Choose durable providers only when per-tenant construction is measurably expensive.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nestjs durable providers, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.