What causes "Invalid Pi model ref: '${modelRef}'. Expected format ' / ' (e.g. 'google/gemini-2.5-pro')." in coleam00/Archon?

Use the exact ' / ' form, e.g. 'google/gemini-2.5-pro'

Invalid Pi model ref: '${modelRef}'. Expected format '<pi-pr

Error message

Invalid Pi model ref: '${modelRef}'. Expected format '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro').

What it means

A model reference was supplied but parsePiModelRef could not parse it into provider/modelId. The ref must be '<pi-provider-id>/<model-id>'. This is a fail-fast on malformed configuration before any session is built.

Source

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

          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];
    const oauthVarName = PI_OAUTH_ENV_VARS[parsed.provider];
    let modelRuntime: Awaited<ReturnType<typeof piCodingAgent.ModelRuntime.create>>;
    let modelRegistry: InstanceType<typeof piCodingAgent.ModelRegistry>;
    // For custom (non-built-in) Pi providers, build a per-call `models.json`
    // with `${VAR}` references substituted against the per-call env. The
    // SDK's session-auth path resolves `${VAR}` from `process.env`, which
    // Archon deliberately keeps empty (per-call secrets ride on
    // `requestOptions.env`); pre-substituting into a per-call file closes

View on GitHub (pinned to 0773b97458)

Solutions

Use the exact '<provider>/<model>' form, e.g. 'google/gemini-2.5-pro'
Check for stray whitespace, quotes, or extra slashes in the model value
Confirm the provider id matches a Pi provider id (run `pi` to list them)

Example fix

// before
model: 'gemini-2.5-pro'
// after
model: 'google/gemini-2.5-pro'

Defensive patterns

Strategy: validation

Validate before calling

const PI_MODEL_REF = /^[^/\s]+\/[^/\s]+$/;
if (!PI_MODEL_REF.test(modelRef ?? '')) {
  throw new Error(`Bad Pi model ref '${modelRef}': use '<provider>/<model-id>'`);
}

Type guard

function isPiModelRef(v: unknown): v is string {
  return typeof v === 'string' && /^[^/\s]+\/[^/\s]+$/.test(v);
}

Try / catch

try {
  await sendQuery(q);
} catch (err) {
  if (err.message.startsWith('Invalid Pi model ref')) {
    console.error(err.message); // message already contains the expected format
  }
  throw err;
}

Prevention

Store model refs as full '<provider>/<model-id>' strings in config
Validate model values with a regex in config-loading code
Copy provider/model ids from `pi`'s model list, not from provider consoles

When it happens

Trigger: sendQuery receiving modelRef values like 'gemini-2.5-pro' (no slash), 'google/gemini/2.5' variants the parser rejects, whitespace-only strings, or a full URL pasted into the model field.

Common situations: Users copying just the model id from a provider console, quoting/escaping issues leaving stray characters, or putting a provider name only ('google').

Related errors

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