Unknown credential vendor '${vendor}'. Known: ${[...KNOWN_VE

Error message

Unknown credential vendor '${vendor}'. Known: ${[...KNOWN_VENDORS].sort().join(', ')}.

What it means

Thrown by deliverCredential when the vendor id has no delivery rule at all: it has no Pi env var, is not ambient, and is not in KNOWN_VENDORS. The error enumerates every deliverable vendor so callers can see what is accepted. Delivery can only turn stored credentials into env/files for vendors the map knows.

Source

Thrown at packages/core/src/credentials/delivery.ts:212

          // Reached only if an oauth row exists under a Pi-backend id (connect
          // guards against this — oauth is anthropic/openai/github-copilot
          // only). The Pi runtime consumes subscriptions via the aggregate
          // auth.json (buildPiAuthJson), not this per-vendor env path.
          throw new Error(
            `Vendor '${vendor}' (Pi backend) has no env-based OAuth delivery; subscriptions reach Pi via auth.json.`
          );
        }
        return { env: { [piEnvVar]: cred.apiKey } };
      }
      if (PI_AMBIENT_VENDORS.includes(vendor)) {
        // Ambient-ONLY vendors (amazon-bedrock — no env var in the map):
        // chains are detected from the environment, never stored — a stored
        // row for one is a connect bug.
        throw new Error(
          `Vendor '${vendor}' uses ambient cloud credentials and has no stored-credential delivery.`
        );
      }
      throw new Error(
        `Unknown credential vendor '${vendor}'. Known: ${[...KNOWN_VENDORS].sort().join(', ')}.`
      );
    }
  }
}

/**
 * A Pi `AuthStorage` `auth.json` entry (see `@earendil-works/pi-coding-agent`
 * `core/auth-storage.d.ts`): an API key or an OAuth blob, keyed by Pi provider id.
 */
type PiAuthCredential = { type: 'api_key'; key: string } | ({ type: 'oauth' } & OAuthCredentials);

/** Relative path (under the per-run artifacts dir) for the generated Pi auth.json. */
export { PI_AUTH_JSON_RELATIVE_PATH };
/** Env var the Pi provider reads to point `AuthStorage` at the per-run auth.json. */
export const PI_AUTH_PATH_ENV = 'ARCHON_PI_AUTH_PATH';

/**

View on GitHub (pinned to 0773b97458)

Solutions

Use a vendor listed in the error message (the sorted KNOWN_VENDORS set).
Normalize the id with normalizeCredentialVendor if it might be a legacy agent-keyed id.
Migrate or delete stale stored rows whose vendor ids no longer exist in the map.
For a genuinely new vendor, add its env-var entry to PI_PROVIDER_ENV_VARS so KNOWN_VENDORS includes it.

Example fix

// before
deliverCredential('claude-code', cred);
// after
import { normalizeCredentialVendor } from './delivery';
deliverCredential(normalizeCredentialVendor('claude'), cred); // 'anthropic'

Defensive patterns

Strategy: validation

Validate before calling

import { KNOWN_VENDORS, normalizeCredentialVendor } from './delivery';
function isDeliverable(vendor: string): boolean {
  return KNOWN_VENDORS.has(normalizeCredentialVendor(vendor));
}

Try / catch

try {
  const r = deliverCredential(vendor, cred);
} catch (e) {
  if ((e as Error).message.startsWith('Unknown credential vendor')) {
    // treat as data/config error: list KNOWN_VENDORS, skip or reconnect
  } else throw e;
}

Prevention

Only write credential rows with ids from KNOWN_VENDORS (after normalizeCredentialVendor).
Migrate stale rows after vendor renames/upgrades.
Validate vendor ids at every boundary (CLI, API, scripts) against the known set.
Register new vendors' env-var rules in PI_PROVIDER_ENV_VARS before storing their keys.

When it happens

Trigger: deliverCredential(vendor, cred) with an id absent from PI_PROVIDER_ENV_KEYS-derived KNOWN_VENDORS — a typo'd vendor, a legacy alias outside {claude, codex, copilot} (only those three normalize), an unregistered community vendor, or a stored row whose vendor id predates a rename.

Common situations: Rows stored by an older binary under a vendor id a newer map no longer contains; callers passing agent ids instead of vendor ids (only claude/codex/copilot are aliased); plugin providers registering vendors with no delivery rule (see error 191).

Related errors

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