{"record":{"id":"2946a6d11b6750b0","repo":"KeygraphHQ/shannon","slug":"shannon-ai-openai-format-applies-to-gateway-runs-o","errorCode":null,"errorMessage":"SHANNON_AI_OPENAI_FORMAT applies to gateway runs only. Set SHANNON_AI_BASE_URL, or unset the format to call OpenAI directly.","messagePattern":"SHANNON_AI_OPENAI_FORMAT applies to gateway runs only\\. Set SHANNON_AI_BASE_URL, or unset the format to call OpenAI directly\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/worker/src/ai/models.ts","lineNumber":311,"sourceCode":" * 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();\n  const credentials = resolveProviderCredentials(providerId);\n  const format = resolveGatewayFormat(providerId, credentials.baseUrl);\n\n  const modelRuntime = await createModelRuntime(providerId, credentials.apiKey);\n\n  const model = resolveModel(modelRuntime, providerId, modelId, credentials.baseUrl, format);","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/KeygraphHQ/shannon/blob/1ae0a142f8525410a688f0309fd003cc5b1d92de/apps/worker/src/ai/models.ts#L293-L329","documentation":"resolveGatewayFormat rejects SHANNON_AI_OPENAI_FORMAT when calling OpenAI directly with no gateway configured. The format only matters behind a custom endpoint that can serve either wire format; a direct OpenAI call uses one fixed API, so the variable is rejected rather than silently dropped.","triggerScenarios":"SHANNON_AI_OPENAI_FORMAT is set, SHANNON_AI_MODEL selects an openai provider, but SHANNON_AI_BASE_URL is unset, then resolveModelSelection() runs.","commonSituations":"Setting the format in anticipation of a proxy/gateway but forgetting SHANNON_AI_BASE_URL; a leftover format var after removing a gateway.","solutions":["Set SHANNON_AI_BASE_URL to the gateway endpoint if you route OpenAI through one.","Unset SHANNON_AI_OPENAI_FORMAT to call OpenAI directly."],"exampleFix":"# before\nexport SHANNON_AI_MODEL=openai:gpt-4o\nexport SHANNON_AI_OPENAI_FORMAT=responses\n# SHANNON_AI_BASE_URL not set\n\n# after (pick one)\nexport SHANNON_AI_BASE_URL=https://my-gateway.example.com   # keep the format\n# OR\nunset SHANNON_AI_OPENAI_FORMAT                                # direct OpenAI","handlingStrategy":"validation","validationCode":"const provider = (process.env.SHANNON_AI_MODEL ?? 'anthropic:claude-sonnet-4-6').split(':')[0];\nconst formatSet = !!process.env.SHANNON_AI_OPENAI_FORMAT?.trim();\nconst hasGateway = !!process.env.SHANNON_AI_BASE_URL?.trim();\nif (formatSet && provider === 'openai' && !hasGateway) {\n  console.error('SHANNON_AI_OPENAI_FORMAT requires SHANNON_AI_BASE_URL. Set the gateway URL or unset the format.');\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set SHANNON_AI_OPENAI_FORMAT together with SHANNON_AI_BASE_URL.","When removing a gateway, unset both SHANNON_AI_BASE_URL and the format variable."],"tags":["config","environment","model-selection","openai","gateway"],"backgroundTag":null,"analyzedSha":"1ae0a142f8525410a688f0309fd003cc5b1d92de","analyzedAt":"2026-08-12T17:40:03.583Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}