coleam00/Archon · error · Error

Model binding '${bindingName}' has invalid thinking options.

Error message

Model binding '${bindingName}' has invalid thinking options.

What it means

readRunModelBindingsMetadata validates a run's persisted model_bindings metadata against runModelBindingsMetadataSchema. When the schema rejects a binding's 'thinking' options, the function throws this error naming the offending binding, because invalid thinking configuration cannot be silently ignored at execution time.

Source

Thrown at packages/workflows/src/model-validation.ts:501

      aliases: Object.fromEntries(
        Object.entries(effective.aliases).map(([name, preset]) => [name, { ...preset }])
      ),
    },
  };
}

/** Read metadata written by this module; malformed external JSON fails explicitly. */
export function readRunModelBindingsMetadata(
  metadata: Record<string, unknown> | undefined
): RunModelBindingsMetadata | undefined {
  const value = metadata?.[RUN_MODEL_BINDINGS_METADATA_KEY];
  if (value === undefined) return undefined;
  const parsed = runModelBindingsMetadataSchema.safeParse(value);
  if (!parsed.success) {
    const path = parsed.error.issues[0]?.path ?? [];
    const bindingName = typeof path[2] === 'string' ? path[2] : 'unknown';
    if (path.includes('thinking')) {
      throw new Error(`Model binding '${bindingName}' has invalid thinking options.`);
    }
    if (path.includes('effort')) {
      throw new Error(`Model binding '${bindingName}' has an invalid effort.`);
    }
    if (path[0] === 'overrides' && (path[1] === 'tiers' || path[1] === 'aliases')) {
      throw new Error(`Workflow run has invalid model_bindings ${path[1]} metadata.`);
    }
    if (path[0] === 'effective') {
      throw new Error('Workflow run has invalid effective model bindings.');
    }
    throw new Error('Workflow run has invalid model_bindings metadata.');
  }

  const tiers = Object.fromEntries(
    Object.entries(parsed.data.overrides.tiers ?? {}).map(([name, preset]) => [
      name,
      normalizePersistedOverridePreset(name, preset),
    ])

View on GitHub (pinned to 0773b97458)

Solutions

Inspect the run's model_bindings metadata and fix or remove the binding's thinking options to match runModelBindingsMetadataSchema
Re-create the run with valid model_bindings instead of reusing the corrupted metadata row
If a schema change caused it, migrate the persisted metadata to the new shape (additively) before running

Example fix

// before (metadata)
"bindings": { "node1": { "thinking": "yes" } }
// after
"bindings": { "node1": { "thinking": { "type": "enabled", "budgetTokens": 2048 } } }

Defensive patterns

Strategy: validation

Validate before calling

import { runModelBindingsMetadataSchema } from '@archon/workflows';
const parsed = runModelBindingsMetadataSchema.safeParse(metadata);
if (!parsed.success) {
  const bad = parsed.error.issues.find(i => i.path.includes('thinking'));
  if (bad) throw new Error(`Binding '${String(bad.path[2])}' has invalid thinking options: ${bad.message}`);
}

Type guard

function hasValidThinkingOptions(b: unknown): b is { thinking?: { type: string; budgetTokens?: number } } {
  return runModelBindingsMetadataSchema.shape.bindings
    .element.pick({ thinking: true }).safeParse(b).success;
}

Try / catch

try {
  await executeWorkflow(runId);
} catch (err) {
  if (err instanceof Error && /has invalid thinking options/.test(err.message)) {
    console.error(`Run ${runId} metadata corrupt: ${err.message}. Re-create or repair model_bindings.`);
  } else throw err;
}

Prevention

Never hand-edit persisted model_bindings metadata; change it through the API/engine
Validate metadata with runModelBindingsMetadataSchema right after writing it in any custom writer
Keep writer and reader binaries on compatible schema versions when resuming runs

When it happens

Trigger: executeWorkflow loads a run whose model_bindings metadata contains a binding entry whose thinking field fails safeParse — e.g. thinking options of the wrong shape/type written by an older or buggy writer, or hand-edited metadata.

Common situations: Hand-editing or backfilling run metadata in the database; older binary writing a thinking shape the current schema no longer accepts; copying run rows between environments with different schema versions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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