diegosouzapw/OmniRoute · error

matched no connected models; falling back to the full pool…

Error message

${label} matched no connected models; falling back to the full pool (OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true)

What it means

Free-model candidate narrowing miss: the family/category+tier filter built from the auto spec matched none of the connected providers' models. When the spec is not family-scoped and OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true, the router warns and falls back to the unfiltered candidate pool instead of failing the request; otherwise it errors with no candidates.

Solutions

  1. Connect or enable a provider that serves models matching the requested family/tier.
  2. Set OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true to allow full-pool fallback for category/tier specs.
  3. Loosen the auto spec (different category/tier) if strict narrowing is intended to fail fast.
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at open-sse/services/autoCombo/virtualFactory.ts:935 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of diegosouzapw/OmniRoute@a179ffed5b (2026-08-25). Data as JSON: /api/errors/6f2c811f7ecf384b. Report an issue: GitHub.

Appendix: source

Thrown at open-sse/services/autoCombo/virtualFactory.ts:935

  const candidateFilter = spec?.family
    ? buildFamilyCandidateFilter(spec.family)
    : spec
      ? buildAutoCandidateFilter(spec.category, spec.tier)
      : null;
  if (candidateFilter) {
    const narrowed = candidatePool.filter((candidate) => candidateFilter(candidate));
    const label = spec?.family
      ? `auto/${spec.family}`
      : `auto/${spec?.category ?? ""}${spec?.tier ? `:${spec.tier}` : ""}`;
    if (narrowed.length > 0) {
      effectivePool = narrowed;
    } else if (
      !spec?.family &&
      (process.env.OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL === "true" ||
        process.env.OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL === "1")
    ) {
      // Opt-in legacy behavior (category/tier only): warn loudly, then keep the full pool.
      log.warn(
        "AUTO",
        `${label} matched no connected models; falling back to the full pool (OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true)`
      );
    } else {
      // Family combos always degrade to an empty pool when unavailable — a family
      // is a hard identity constraint, not a soft optimization bias, so there is
      // no sensible "fall back to the full pool" behavior for it.
      warnEmptyAutoPoolOnce(
        label,
        `${label} matched no connected models; returning an empty pool.${spec?.family ? "" : ' Set OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=true to restore the legacy "use full pool" behavior.'}`
      );
      effectivePool = [];
    }
  }

  // Subscription-first routing (`auto/subscription`, `auto/thrifty`). Applied
  // AFTER the category/tier narrowing above because, unlike every other tier,
  // these two select on the connection's billing class and its live quota

View on GitHub (pinned to a179ffed5b)