What causes "Pi requires `adapterConfig.model` in provider/model format." in paperclipai/paperclip?

Set adapterConfig.model to a non-empty model id that pi recognizes.

paperclipai/paperclip · error · Error

Pi requires `adapterConfig.model` in provider/model format.

Error message

Pi requires `adapterConfig.model` in provider/model format.

What it means

Thrown by ensurePiModelConfiguredAndAvailable (pi-local) when adapterConfig.model is empty after trimming. Unlike the OpenCode validator (392), this check only rejects emptiness — it does not enforce a provider/model slash format; the format expectation in the message is advisory. The function then proceeds to discovery.

Source

Thrown at packages/adapters/pi-local/src/server/models.ts:177

  const now = Date.now();
  pruneExpiredDiscoveryCache(now);
  const cached = discoveryCache.get(key);
  if (cached && cached.expiresAt > now) return cached.models;

  const models = await discoverPiModels({ command, cwd, env });
  discoveryCache.set(key, { expiresAt: now + MODELS_CACHE_TTL_MS, models });
  return models;
}

export async function ensurePiModelConfiguredAndAvailable(input: {
  model?: unknown;
  command?: unknown;
  cwd?: unknown;
  env?: unknown;
}): Promise<AdapterModel[]> {
  const model = asString(input.model, "").trim();
  if (!model) {
    throw new Error("Pi requires `adapterConfig.model` in provider/model format.");
  }

  const models = await discoverPiModelsCached({
    command: input.command,
    cwd: input.cwd,
    env: input.env,
  });

  if (models.length === 0) {
    throw new Error("Pi returned no models. Run `pi --list-models` and verify provider auth.");
  }

  if (!models.some((entry) => entry.id === model)) {
    const sample = models.slice(0, 12).map((entry) => entry.id).join(", ");
    throw new Error(
      `Configured Pi model is unavailable: ${model}. Available models: ${sample}${models.length > 12 ? ", ..." : ""}`,
    );
  }

View on GitHub (pinned to 67001ec6eb)

Solutions

Set adapterConfig.model to a non-empty model id that pi recognizes.
Run `pi --list-models` to find valid model ids, then assign one.
If generating config programmatically, default model to a known-good id.

Example fix

// before
adapterConfig = { /* model missing */ }
// after
adapterConfig = { model: "<provider>/<model>" }

Defensive patterns

Strategy: type-guard

Validate before calling

const model = asString(adapterConfig.model, "").trim();
if (!model) {
  throw new Error("adapterConfig.model is required for the Pi adapter before starting the run.");
}

Type guard

function hasPiModel(input: { model?: unknown }): input is { model: string } {
  return typeof input.model === "string" && input.model.trim().length > 0;
}

Prevention

Set adapterConfig.model at agent creation; reject empty in config schemas.
Populate model options from `pi --list-models` in the UI.
Default to a known-good model id when generating config programmatically.

When it happens

Trigger: asString(input.model, "").trim() is empty when ensurePiModelConfiguredAndAvailable is called.

Common situations: adapterConfig.model never set for a Pi-backed agent; the field was cleared by a config edit/migration; the model was passed as undefined or whitespace.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/1fb581d798b0787f. Report an issue: GitHub.