What causes "adapter not provided: ${name}" in hcengineering/platform?

Ensure at least one adapter is registered and set as conf.defaultAdapter

adapter not provided: ${name}

Error message

adapter not provided: ${name}

What it means

getAdapterByName resolves a named DbAdapter from the adapter registry. Despite the ?? this.defaultAdapter fallback in the source, if both the named lookup and defaultAdapter are undefined (no adapters configured at all), it throws 'adapter not provided: <name>'.

Source

Thrown at foundations/server/packages/core/src/dbAdapterManager.ts:205

        await o.close()
      } catch (err: any) {
        Analytics.handleError(err)
      }
    }
  }

  getAdapterName (domain: Domain): string {
    const adapterName = this.conf.domains[domain]
    return adapterName ?? this.conf.defaultAdapter
  }

  getAdapterByName (name: string): DbAdapter {
    if (name === this.conf.defaultAdapter) {
      return this.defaultAdapter
    }
    const adapter = this.adapters.get(name) ?? this.defaultAdapter
    if (adapter === undefined) {
      throw new Error('adapter not provided: ' + name)
    }

    return adapter
  }

  public getAdapter (domain: Domain, requireExists: boolean): DbAdapter {
    const name = this.conf.domains[domain] ?? '#default'
    const adapter = this.adapters.get(name) ?? this.defaultAdapter
    if (adapter === undefined) {
      throw new Error('adapter not provided: ' + name)
    }

    const info = this.getDomainInfo(domain)

    if (!info.exists && !requireExists) {
      return this.emptyAdapter
    }
    // If we require it exists, it will be exists

View on GitHub (pinned to 63e28dc964)

Solutions

Ensure at least one adapter is registered and set as conf.defaultAdapter
Verify the requested adapter name exists in the adapters config
Check that the configuration file loading didn't silently fail, leaving adapters empty

Example fix

// before
connect('myDomain', { name: 'unconfigured-db' })
// after
// register the adapter first or use the default
connect('myDomain', { name: conf.defaultAdapter })

Defensive patterns

Strategy: try-catch

Validate before calling

if (!manager.hasAdapter(name) && !manager.hasDefaultAdapter()) {
  throw new Error(`adapter '${name}' not configured and no default adapter`)
}

Try / catch

try {
  const adapter = manager.getAdapterByName(name)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('adapter not provided')) {
    console.error(`DB adapter '${name}' is not configured; check server config`)
  } else throw err
}

Prevention

Always configure conf.defaultAdapter as a safety net
Keep adapter names in typed constants instead of raw strings
Validate at boot that every adapter referenced by domains/plugins is registered

When it happens

Trigger: Calling adapter(name) where name is not in the registry AND the default adapter was never provided to DbAdapterManager (empty or misloaded adapters configuration).

Common situations: Server started without any DB adapters registered; plugin/domain code requests an adapter name that was never configured; config file failed to load so the adapters map is empty.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/4d0886432a982263. Report an issue: GitHub.