{"record":{"id":"fb37b28365f0e197","repo":"mastra-ai/mastra","slug":"failed-to-fetch-from-models-dev-response-status","errorCode":null,"errorMessage":"Failed to fetch from models.dev: ${response.statusText}","messagePattern":"Failed to fetch from models\\.dev: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/gateways/models-dev.ts","lineNumber":135,"sourceCode":"\nexport class ModelsDevGateway extends MastraModelGateway {\n  readonly id = 'models.dev';\n  readonly name = 'models.dev';\n\n  private providerConfigs: Record<string, ProviderConfig> = {};\n  private attachmentCapabilities: AttachmentCapabilities = {};\n  private temperatureCapabilities: TemperatureCapabilities = {};\n  private structuredOutputCapabilities: StructuredOutputCapabilities = {};\n\n  constructor(providerConfigs?: Record<string, ProviderConfig>) {\n    super();\n    if (providerConfigs) this.providerConfigs = providerConfigs;\n  }\n\n  async fetchProviders(): Promise<Record<string, ProviderConfig>> {\n    const response = await fetch('https://models.dev/api.json');\n    if (!response.ok) {\n      throw new Error(`Failed to fetch from models.dev: ${response.statusText}`);\n    }\n\n    const data = (await response.json()) as ModelsDevResponse;\n\n    // Reset capability maps so removed providers/models are not retained across syncs\n    this.attachmentCapabilities = {};\n    this.temperatureCapabilities = {};\n    this.structuredOutputCapabilities = {};\n\n    const providerConfigs: Record<string, ProviderConfig> = {};\n\n    for (const [providerId, providerInfo] of Object.entries(data)) {\n      // Skip excluded providers\n      if (EXCLUDED_PROVIDERS.includes(providerId)) continue;\n      // Skip non-provider entries (if any)\n      if (!providerInfo || typeof providerInfo !== 'object' || !providerInfo.models) continue;\n\n      // Use provider ID as-is (keep hyphens for consistency)","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/gateways/models-dev.ts#L117-L153","documentation":"The models.dev registry gateway fetches https://models.dev/api.json to sync provider/model metadata; the HTTP response was not ok. The error carries response.statusText. Until this sync succeeds, the gateway can't resolve provider configs, API key env vars, or model capabilities.","triggerScenarios":"Calling fetchProviders() when models.dev returns non-2xx: service outage, CDN error, rate limiting, DNS/network failure, or a proxy returning 403/502.","commonSituations":"Corporate proxy or firewall blocking models.dev; offline/air-gapped environments; models.dev downtime; aggressive rate limiting on shared CI runners.","solutions":["Check statusText/network access: curl https://models.dev/api.json from the same environment.","Retry with backoff — often transient outage or throttling.","Provide providerConfigs manually (the constructor accepts providerConfigs) to skip reliance on the live fetch.","Cache a previously fetched api.json locally and inject it in offline/CI environments."],"exampleFix":"// before\nconst gw = new ModelsDevGateway();\nawait gw.fetchProviders(); // fails offline\n// after\nconst cached = require('./models-dev-cache.json');\nconst gw = new ModelsDevGateway({ providerConfigs: cached });","handlingStrategy":"fallback","validationCode":"const res = await fetch('https://models.dev/api.json');\nif (!res.ok) throw new Error(`models.dev unreachable (HTTP ${res.status}) — prepare cached providerConfigs`);","typeGuard":null,"tryCatchPattern":"let providers;\ntry {\n  providers = await gw.fetchProviders();\n} catch (e) {\n  if (/Failed to fetch from models.dev/.test(e.message)) {\n    providers = require('./models-dev-cache.json'); // last-known-good snapshot\n  } else throw e;\n}","preventionTips":["Vendor/cache a snapshot of api.json for offline/CI use.","Initialize gateways with providerConfigs so runtime doesn't depend on a live fetch.","Retry with backoff on 5xx/timeouts.","Alert on registry sync failures in monitoring."],"tags":["network","http","models-dev","registry"],"backgroundTag":"http-request-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}