Provider(s) ${entry.agents.join(', ')} declare credential ve

Error message

Provider(s) ${entry.agents.join(', ')} declare credential vendor '${entry.vendor}' (api_key) but the delivery map has no rule for it.

What it means

Thrown by getVendorCatalog when a registered provider statically declares an api_key credential vendor that the delivery map (KNOWN_VENDORS, derived from PI_PROVIDER_ENV_VARS) has no rule for. This is a deliberate fail-loud registration-time invariant: a key could be connected but never delivered to the agent, so the catalog refuses to build rather than silently offering an undeliverable credential.

Source

Thrown at packages/core/src/credentials/catalog.ts:65

      const existing = catalog.get(spec.vendor);
      if (existing) {
        existing.agents.push(reg.id);
        for (const k of spec.kinds) {
          if (!existing.kinds.includes(k)) existing.kinds.push(k);
        }
      } else {
        catalog.set(spec.vendor, {
          vendor: spec.vendor,
          displayName: spec.displayName,
          kinds: [...spec.kinds],
          agents: [reg.id],
        });
      }
    }
  }
  for (const entry of catalog.values()) {
    if (entry.kinds.includes('api_key') && !KNOWN_VENDORS.has(entry.vendor)) {
      throw new Error(
        `Provider(s) ${entry.agents.join(', ')} declare credential vendor '${entry.vendor}' ` +
          '(api_key) but the delivery map has no rule for it.'
      );
    }
  }
  return catalog;
}

/** Sorted vendor ids a user can connect an API key for. */
export function listConnectableVendors(): string[] {
  return [...getVendorCatalog().values()]
    .filter(e => e.kinds.includes('api_key'))
    .map(e => e.vendor)
    .sort();
}

/** Whether `id` (vendor-canonical or legacy agent-keyed) is API-key connectable. */
export function isConnectableVendor(id: string): boolean {

View on GitHub (pinned to 0773b97458)

Solutions

Add a delivery rule: ensure the vendor id has an entry in PI_PROVIDER_ENV_VARS (@archon/providers, regenerated via `bun run check:pi-vendor-map`) so KNOWN_VENDORS includes it.
Fix the provider registration: correct the vendor id in the provider's `credentials.specs` to match a known vendor.
If the vendor is genuinely ambient-only, change the spec's kinds from 'api_key' to 'ambient' instead of declaring an undeliverable key kind.
Run `bun run check:pi-vendor-map` to confirm the generated vendor map and registrations agree.

Example fix

// before (provider registration)
specs: [{ vendor: 'anthropicx', kinds: ['api_key'] }]
// after
specs: [{ vendor: 'anthropic', kinds: ['api_key'] }]

Defensive patterns

Strategy: validation

Validate before calling

import { KNOWN_VENDORS } from './delivery';
function validateRegistration(specs: { vendor: string; kinds: string[] }[]): string | null {
  for (const s of specs)
    if (s.kinds.includes('api_key') && !KNOWN_VENDORS.has(s.vendor))
      return `vendor '${s.vendor}' has no delivery rule`;
  return null;
}

Try / catch

try {
  const catalog = getVendorCatalog();
} catch (e) {
  const m = /declare credential vendor '([^']+)'/.exec((e as Error).message);
  if (m) throw new Error(`Fix provider registration or add delivery rule for '${m[1]}'`, { cause: e });
  throw e;
}

Prevention

Derive vendor ids from a shared constant shared between registration and the env-var map instead of string literals.
Run `bun run check:pi-vendor-map` in CI to catch drift between registrations and the generated map.
Add a unit test that builds the catalog over all builtin + community providers.
Never declare 'api_key' kind for ambient-only vendors.

When it happens

Trigger: Booting the server or calling getVendorCatalog/listConnectableVendors after registering a provider whose `credentials.specs` includes a vendor id absent from PI_PROVIDER_ENV_VARS — typically after adding a new community provider, renaming a vendor id, or a pi-ai SDK upgrade that dropped/regenerated the env-var map.

Common situations: Developing a custom provider plugin and misspelling the vendor id; upgrading @earendil-works/pi-ai so the generated PI_PROVIDER_ENV_VARS loses a key; moving a vendor to ambient-only in the map while a registration still declares api_key.

Related errors

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