Pi provider requires a model. Set `model` on the workflow no

Error message

Pi provider requires a model. Set `model` on the workflow node or `assistants.pi.model` in .archon/config.yaml, or select a default model in the `pi` CLI (writes defaultProvider/defaultModel to ~/.pi/agent/settings.json). Format: '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro').

What it means

sendQuery needs a model reference ('<pi-provider-id>/<model-id>') to build the Pi session. It resolves the ref from the workflow node's `model`, the config's `assistants.pi.model`, and finally the pi CLI's default settings (~/.pi/agent/settings.json); if none yields a ref, it throws with instructions for all three sources.

Source

Thrown at packages/providers/src/community/pi/provider.ts:398

        // that would otherwise surface them).
        for (const { scope, error: settingsErr } of settingsManager.drainErrors()) {
          getLog().warn({ scope, err: settingsErr }, 'pi.settings_default_model_read_error');
        }
        const provider = settings.defaultProvider?.trim();
        const modelId = settings.defaultModel?.trim();
        if (provider && modelId) {
          modelRef = `${provider}/${modelId}`;
          getLog().info({ modelRef }, 'pi.model_defaulted_from_settings');
        }
      } catch (err) {
        // Non-fatal: settings.json may be absent (user never ran `pi`) or
        // unreadable. Fall through to the explicit "requires a model" error
        // below rather than swallowing the missing-model condition.
        getLog().debug({ err }, 'pi.settings_default_model_read_failed');
      }
    }
    if (!modelRef) {
      throw new Error(
        'Pi provider requires a model. Set `model` on the workflow node or `assistants.pi.model` in .archon/config.yaml, ' +
          'or select a default model in the `pi` CLI (writes defaultProvider/defaultModel to ~/.pi/agent/settings.json). ' +
          "Format: '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro')."
      );
    }
    const parsed = parsePiModelRef(modelRef);
    if (!parsed) {
      throw new Error(
        `Invalid Pi model ref: '${modelRef}'. Expected format '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro').`
      );
    }

    // 2. Build ModelRuntime + ModelRegistry. Both read on every sendQuery —
    //    user edits to auth.json or models.json take effect without restart.
    //    The registry is a thin facade over the runtime — extension providers
    //    call registerProvider() on it during bindExtensions() to add their
    //    models (phase 2 resolution).
    const envVarName = PI_PROVIDER_ENV_VARS[parsed.provider];

View on GitHub (pinned to 0773b97458)

Solutions

Set `model: 'google/gemini-2.5-pro'` (or another ref) on the workflow AI node
Set assistants.pi.model in .archon/config.yaml
Run `pi` locally, select a default model (writes defaultProvider/defaultModel to ~/.pi/agent/settings.json)
If a default was set, verify ~/.pi/agent/settings.json is readable and contains defaultModel

Example fix

// before (.archon/config.yaml)
assistants:
  pi: {}
// after
assistants:
  pi:
    model: 'google/gemini-2.5-pro'

Defensive patterns

Strategy: validation

Validate before calling

function resolvePiModelRef(node, config, home = process.env.HOME) {
  if (node.model) return node.model;
  if (config?.assistants?.pi?.model) return config.assistants.pi.model;
  try {
    const s = JSON.parse(readFileSync(join(home, '.pi/agent/settings.json'), 'utf8'));
    if (s.defaultProvider && s.defaultModel) return `${s.defaultProvider}/${s.defaultModel}`;
  } catch { /* fall through */ }
  return null;
}
if (!resolvePiModelRef(node, config)) throw new Error('No Pi model configured');

Type guard

function hasModelRef(x: unknown): x is { model: string } {
  return typeof x === 'object' && x !== null && typeof (x as any).model === 'string' && (x as any).model.length > 0;
}

Try / catch

try {
  await sendQuery(q);
} catch (err) {
  if (err.message.includes('Pi provider requires a model')) {
    console.error('Set model on the node or assistants.pi.model in .archon/config.yaml, or run `pi` and pick a default');
  }
  throw err;
}

Prevention

Set a default assistants.pi.model in .archon/config.yaml for every deployment
Run `pi` once and select a default model when provisioning a machine
Verify settings.json exists and is readable in container images

When it happens

Trigger: Calling sendQuery when the node has no `model`, .archon/config.yaml has no assistants.pi.model, and ~/.pi/agent/settings.json lacks defaultModel (or its read failed, which is logged and intentionally falls through to this error).

Common situations: Fresh installs where `pi` was never launched and /login never run, CI containers without a home-dir Pi settings file, or config where the model key was renamed/omitted.

Related errors

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