KeygraphHQ/shannon · error · Error

SHANNON_AI_OPENAI_FORMAT applies to openai models only, but

Error message

SHANNON_AI_OPENAI_FORMAT applies to openai models only, but SHANNON_AI_MODEL selects "${providerId}". ${providerId} serves a single API, so there is no format to choose.

What it means

resolveGatewayFormat rejects SHANNON_AI_OPENAI_FORMAT when the selected provider is not 'openai'. The format variable only chooses between OpenAI's two wire formats; every other provider (anthropic, xai, amazon-bedrock, ...) serves a single API in pi's registry, so setting it elsewhere has no effect and signals a misconfiguration.

Source

Thrown at apps/worker/src/ai/models.ts:305

  if (!reference) return undefined;

  return pointAtGateway({ ...reference, id: modelId, name: modelId }, providerId, baseUrl, format);
}

/**
 * Validate SHANNON_AI_OPENAI_FORMAT against the rest of the configuration and
 * return the format a gateway run should use.
 *
 * The variable only reaches a request when both an OpenAI model and a gateway
 * are configured, so it is rejected outside that combination rather than
 * silently ignored.
 */
export function resolveGatewayFormat(providerId: string, baseUrl: string | undefined): OpenAiFormat {
  const configured = resolveOpenAiFormat();
  if (!configured) return DEFAULT_OPENAI_FORMAT;

  if (providerId !== 'openai') {
    throw new Error(
      `SHANNON_AI_OPENAI_FORMAT applies to openai models only, but SHANNON_AI_MODEL selects "${providerId}". ` +
        `${providerId} serves a single API, so there is no format to choose.`,
    );
  }
  if (!baseUrl) {
    throw new Error(
      'SHANNON_AI_OPENAI_FORMAT applies to gateway runs only. Set SHANNON_AI_BASE_URL, or unset the format to call OpenAI directly.',
    );
  }
  return configured;
}

/**
 * Resolve SHANNON_AI_MODEL, build a ModelRuntime primed with the provider's
 * credential, and look the model up in it.
 */
export async function resolveModelSelection(): Promise<ModelSelection> {
  const { providerId, modelId } = resolveModelSpec();

View on GitHub (pinned to 1ae0a142f8)

Solutions

Unset SHANNON_AI_OPENAI_FORMAT when SHANNON_AI_MODEL is not an openai provider.
If you intended an OpenAI-format gateway, set SHANNON_AI_MODEL to an 'openai:<model-id>' spec.

Example fix

# before
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
export SHANNON_AI_OPENAI_FORMAT=responses   # has no effect for anthropic

# after
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
unset SHANNON_AI_OPENAI_FORMAT

Defensive patterns

Strategy: validation

Validate before calling

const model = process.env.SHANNON_AI_MODEL ?? 'anthropic:claude-sonnet-4-6';
const provider = model.slice(0, model.indexOf(':')) || model;
const formatSet = !!process.env.SHANNON_AI_OPENAI_FORMAT?.trim();
if (formatSet && provider !== 'openai') {
  console.error(`SHANNON_AI_OPENAI_FORMAT has no effect for provider "${provider}". Unset it or switch to an openai model.`);
  process.exit(1);
}

Prevention

Treat SHANNON_AI_OPENAI_FORMAT as coupled to an openai provider — unset it whenever you change providers.
Keep provider-specific env vars in one config block so switching providers clears stale ones.

When it happens

Trigger: SHANNON_AI_OPENAI_FORMAT is set to a valid value AND SHANNON_AI_MODEL selects a non-openai provider, then resolveModelSelection() runs during preflight.

Common situations: Switching SHANNON_AI_MODEL from an openai gateway to anthropic/xai but leaving the format variable exported; copy-pasting a gateway config block across providers.

Related errors

AI-assisted analysis of KeygraphHQ/shannon@1ae0a142f8 (2026-08-12). Data as JSON: /api/errors/7588e9bd4f0f6541. Report an issue: GitHub.