{"record":{"id":"7588e9bd4f0f6541","repo":"KeygraphHQ/shannon","slug":"shannon-ai-openai-format-applies-to-openai-models","errorCode":null,"errorMessage":"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.","messagePattern":"SHANNON_AI_OPENAI_FORMAT applies to openai models only, but SHANNON_AI_MODEL selects \"(.+?)\"\\. (.+?) serves a single API, so there is no format to choose\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/worker/src/ai/models.ts","lineNumber":305,"sourceCode":"  if (!reference) return undefined;\n\n  return pointAtGateway({ ...reference, id: modelId, name: modelId }, providerId, baseUrl, format);\n}\n\n/**\n * Validate SHANNON_AI_OPENAI_FORMAT against the rest of the configuration and\n * return the format a gateway run should use.\n *\n * The variable only reaches a request when both an OpenAI model and a gateway\n * are configured, so it is rejected outside that combination rather than\n * silently ignored.\n */\nexport function resolveGatewayFormat(providerId: string, baseUrl: string | undefined): OpenAiFormat {\n  const configured = resolveOpenAiFormat();\n  if (!configured) return DEFAULT_OPENAI_FORMAT;\n\n  if (providerId !== 'openai') {\n    throw new Error(\n      `SHANNON_AI_OPENAI_FORMAT applies to openai models only, but SHANNON_AI_MODEL selects \"${providerId}\". ` +\n        `${providerId} serves a single API, so there is no format to choose.`,\n    );\n  }\n  if (!baseUrl) {\n    throw new Error(\n      'SHANNON_AI_OPENAI_FORMAT applies to gateway runs only. Set SHANNON_AI_BASE_URL, or unset the format to call OpenAI directly.',\n    );\n  }\n  return configured;\n}\n\n/**\n * Resolve SHANNON_AI_MODEL, build a ModelRuntime primed with the provider's\n * credential, and look the model up in it.\n */\nexport async function resolveModelSelection(): Promise<ModelSelection> {\n  const { providerId, modelId } = resolveModelSpec();","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/KeygraphHQ/shannon/blob/1ae0a142f8525410a688f0309fd003cc5b1d92de/apps/worker/src/ai/models.ts#L287-L323","documentation":"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.","triggerScenarios":"SHANNON_AI_OPENAI_FORMAT is set to a valid value AND SHANNON_AI_MODEL selects a non-openai provider, then resolveModelSelection() runs during preflight.","commonSituations":"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.","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."],"exampleFix":"# before\nexport SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6\nexport SHANNON_AI_OPENAI_FORMAT=responses   # has no effect for anthropic\n\n# after\nexport SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6\nunset SHANNON_AI_OPENAI_FORMAT","handlingStrategy":"validation","validationCode":"const model = process.env.SHANNON_AI_MODEL ?? 'anthropic:claude-sonnet-4-6';\nconst provider = model.slice(0, model.indexOf(':')) || model;\nconst formatSet = !!process.env.SHANNON_AI_OPENAI_FORMAT?.trim();\nif (formatSet && provider !== 'openai') {\n  console.error(`SHANNON_AI_OPENAI_FORMAT has no effect for provider \"${provider}\". Unset it or switch to an openai model.`);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["config","environment","model-selection","openai","gateway"],"backgroundTag":null,"analyzedSha":"1ae0a142f8525410a688f0309fd003cc5b1d92de","analyzedAt":"2026-08-12T17:40:03.583Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}