coleam00/Archon · error · UnknownProviderError

Unknown provider: '${requestedProvider}'. Available: ${regis

Error message

Unknown provider: '${requestedProvider}'. Available: ${registeredProviders.join(', ')}

What it means

getAgentProvider looks up a registered provider by ID and instantiates it via its factory. The ID was not found in the registry, so it throws UnknownProviderError listing every currently registered provider ID. This guards against running work against a misspelled or not-yet-registered provider.

Source

Thrown at packages/providers/src/registry.ts:63

 * Register a provider. Throws on duplicate registration.
 */
export function registerProvider(entry: ProviderRegistration): void {
  if (registry.has(entry.id)) {
    throw new Error(`Provider '${entry.id}' is already registered`);
  }
  assertValidCapabilities(entry);
  registry.set(entry.id, entry);
  getLog().debug({ provider: entry.id, builtIn: entry.builtIn }, 'provider.registered');
}

/**
 * Get an instantiated agent provider by ID.
 * @throws UnknownProviderError if not registered
 */
export function getAgentProvider(id: string): IAgentProvider {
  const entry = registry.get(id);
  if (!entry) {
    throw new UnknownProviderError(id, [...registry.keys()]);
  }
  getLog().debug({ provider: id }, 'provider_selected');
  return entry.factory();
}

/**
 * Get the full registration entry for a provider.
 * @throws UnknownProviderError if not registered
 */
export function getRegistration(id: string): ProviderRegistration {
  const entry = registry.get(id);
  if (!entry) {
    throw new UnknownProviderError(id, [...registry.keys()]);
  }
  return entry;
}

/**

View on GitHub (pinned to 0773b97458)

Solutions

Compare your provider ID against the 'Available:' list in the error and fix the spelling
Ensure registerBuiltinProviders()/the provider pack registration runs before getAgentProvider is called
Import the module that registers the desired provider at startup
Update stale config to the current provider ID after a rename

Example fix

// before
const provider = getAgentProvider('claude-code');
// after (matches a registered id)
const provider = getAgentProvider('claude');

Defensive patterns

Strategy: try-catch

Validate before calling

import { getRegisteredProviders } from '@archon/providers';
if (!getRegisteredProviders().includes(id)) {
  console.error(`Provider '${id}' not registered. Available: ${getRegisteredProviders().join(', ')}`);
}

Try / catch

import { UnknownProviderError } from '@archon/providers';
try {
  const provider = getAgentProvider(id);
} catch (err) {
  if (err instanceof UnknownProviderError) {
    console.error(`'${err.requestedProvider}' is not registered. Available: ${err.registeredProviders.join(', ')}`);
  }
  throw err;
}

Prevention

Copy provider IDs from the error's 'Available:' list, never from memory
Ensure registerBuiltinProviders() runs at startup before any lookup
Grep configs for provider IDs after any provider rename

When it happens

Trigger: Calling getAgentProvider(id) with an id that was never passed to registerProvider (typo, provider pack not loaded, call before registerBuiltinProviders runs).

Common situations: Typo in config ('claude-code' vs 'claude'); provider registration module not imported at startup; builtin registration skipped in a test harness; renamed provider ID after an upgrade while old config still references it.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/444add82f45d7b43. Report an issue: GitHub.