Run config key 'assistants.pi.env' cannot apply: Pi extensio

Error message

Run config key 'assistants.pi.env' cannot apply: Pi extension environment mutates process.env and is process-scoped.

What it means

Archon run configs allow per-provider assistant defaults, but the 'pi' provider rejects an 'env' key. Pi extension environment variables mutate process.env, which is process-scoped and cannot be applied per-run, so the config layer refuses the key at normalization time instead of silently ignoring it.

Source

Thrown at packages/core/src/config/run-config.ts:126

      throw new Error(
        `Invalid run config at '${issuePath}': unknown provider '${error.issue.provider}'.` +
          (available ? ` Available: ${available}.` : ' No providers are registered.')
      );
    }
    throw new Error(`Invalid run config at '${issuePath}': ${error.message}.`);
  }
}

/** Validate and normalize constraints owned by the live provider registry and lifecycle. */
export function normalizeRunConfigSemantics(layer: WorkflowRunConfigLayer): WorkflowRunConfigLayer {
  if (layer.assistant !== undefined) {
    assertRegisteredProvider(layer.assistant, 'assistant');
  }
  const assistants: Record<string, Record<string, unknown>> = {};
  for (const [provider, defaults] of Object.entries(layer.assistants ?? {})) {
    assertRegisteredProvider(provider, `assistants.${provider}`);
    if (provider === 'pi' && Object.hasOwn(defaults, 'env')) {
      throw new Error(
        "Run config key 'assistants.pi.env' cannot apply: Pi extension environment mutates " +
          'process.env and is process-scoped.'
      );
    }
    if (provider === 'pi' && Object.hasOwn(defaults, 'maxConcurrent')) {
      throw new Error(
        "Run config key 'assistants.pi.maxConcurrent' cannot apply: Pi concurrency is " +
          'initialized once for the process lifetime.'
      );
    }
    try {
      assistants[provider] = getRegistration(provider).parseRunConfig(defaults);
    } catch (error) {
      if (error instanceof InvalidProviderRunConfigError) {
        const suffix = error.fieldPath ? `.${error.fieldPath}` : '';
        throw new Error(
          `Invalid run config at 'assistants.${provider}${suffix}': ${error.message}.`
        );

View on GitHub (pinned to 0773b97458)

Solutions

Remove the 'env' key from assistants.pi in the run config
Set Pi extension environment variables in the process environment (shell, .env, or process.env) instead of the run config
Move env setup to the deployment/startup layer that launches the Archon process

Example fix

// before
assistants:
  pi:
    env:
      PI_TOKEN: abc
// after
assistants:
  pi: {}  # set PI_TOKEN in the process environment instead

Defensive patterns

Strategy: validation

Validate before calling

function assertPiAssistantDefaults(defaults) { if (defaults && ('env' in defaults)) throw new Error("assistants.pi.env is not supported; set env in the process environment"); }

Type guard

function hasPiEnv(layer) { return typeof layer?.assistants?.pi === 'object' && layer.assistants.pi !== null && 'env' in layer.assistants.pi; }

Try / catch

try { cfg = parseWorkflowRunConfig(doc, source); } catch (e) { if (String(e.message).includes("assistants.pi.env")) { console.error('Move pi env vars to the process environment'); } throw e; }

Prevention

Never put 'env' under assistants.pi; keep pi env in shell/.env/process startup
Lint run config files for the assistants.pi.env key in CI
Share a typed schema of valid pi assistant keys with the team

When it happens

Trigger: Calling runConfig(), parseWorkflowRunConfig(), or unsealWorkflowRunConfig() with a config layer containing assistants: { pi: { env: {...} } }.

Common situations: Copying a general assistant env block into the pi assistant section of a run config or workflow frontmatter; assuming all providers support per-run env overrides.

Related errors

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