affaan-m/ECC · error · Error

Unknown session adapter

Error message

Unknown session adapter: ${id}

What it means

getAdapter looks up an adapter by its exact id inside the registry's adapter list and throws when no registered adapter has that id. It is the registry's fail-fast guard: any caller resolving an adapterId (e.g. from a normalized structured target's context) must use a currently registered adapter id.

Solutions

1. Log/inspect the available ids with registry.listAdapters() and correct the id string to a listed adapter id.
2. If using a custom adapters array, register the missing adapter (e.g. include the claude adapter factory) so the referenced id exists.
3. If the id comes from persisted config/targets, migrate those records to the new adapter id after an upgrade or rename.
4. Wrap calls in try-catch and fall back to adapter auto-selection by omitting adapterId so canOpen() matching picks an adapter.

Example fix

// before
const adapter = registry.getAdapter('claude-code'); // typo

// after
const ids = registry.listAdapters().map(a => a.id);
const adapter = registry.getAdapter(ids.includes('claude-code') ? 'claude-code' : 'claude');

const known = new Set(registry.listAdapters().map(a => a.id));
if (!known.has(id)) console.warn(`id ${id} not registered; available: ${[...known].join(', ')}`);

try {
  adapter = registry.getAdapter(id);
} catch (err) {
  if (String(err.message).startsWith('Unknown session adapter')) {
    adapter = registry.listAdapters()[0]; // or prompt user
  } else throw err;
}

When it happens

Trigger: Calling registry.getAdapter('unknown-id'); or a structured target carrying adapterId: 'codex' when no codex adapter was registered (createSessionAdapters called with a subset of adapters); or TARGET_TYPE_TO_ADAPTER_ID mapping a type to an adapter id that was not included in the adapters list.

Common situations: Typo in the adapter id ('claude-code' vs 'claude'); custom registry constructed with a restricted adapter list while old persisted targets still reference removed adapter ids; upgrading the library where an adapter was renamed or deleted but stored session targets keep the old id.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• No session adapter matched target
• Structured session targets require a non-empty type
• No provider registered for type
• Template content must be a non-empty string
• Template name must be a non-empty string

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/cc57457acf8f9fc3. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/session-adapters/registry.js:107

      context: nextContext
    };
  }

  return {
    target: value,
    context: nextContext
  };
}

function createAdapterRegistry(options = {}) {
  const adapters = options.adapters || createDefaultAdapters(options);

  return {
    adapters,
    getAdapter(id) {
      const adapter = adapters.find(candidate => candidate.id === id);
      if (!adapter) {
        throw new Error(`Unknown session adapter: ${id}`);
      }

      return adapter;
    },
    listAdapters() {
      return adapters.map(adapter => ({
        id: adapter.id,
        description: adapter.description || '',
        targetTypes: Array.isArray(adapter.targetTypes) ? [...adapter.targetTypes] : []
      }));
    },
    select(target, context = {}) {
      const normalized = normalizeStructuredTarget(target, context);
      const adapter = normalized.context.adapterId
        ? this.getAdapter(normalized.context.adapterId)
        : adapters.find(candidate => candidate.canOpen(normalized.target, normalized.context));
      if (!adapter) {
        throw new Error(`No session adapter matched target: ${target}`);

View on GitHub (pinned to 8321021c54)