{"record":{"id":"cace4284af2d5c86","repo":"mastra-ai/mastra","slug":"model-config-provider-config-modelid-is-a-me","errorCode":null,"errorMessage":"Model ${config.provider}/${config.modelId} is a metadata-only stub. The actual model instance should be resolved from the run registry.","messagePattern":"Model (.+?)/(.+?) is a metadata-only stub\\. The actual model instance should be resolved from the run registry\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/durable/utils/resolve-runtime.ts","lineNumber":453,"sourceCode":"  } catch (error) {\n    logger?.debug?.(`[DurableAgent:${agentId}] Failed to rebuild tools from Mastra for run ${runId}: ${error}`);\n    return undefined;\n  }\n}\n\n/**\n * Resolve the language model from serialized config.\n *\n * Note: This is a fallback when the model is not in the run registry.\n * The preferred approach is to store the actual model instance in the\n * run registry during preparation and retrieve it via runRegistry.getModel().\n *\n * This fallback returns a metadata-only stub that will fail the\n * isSupportedLanguageModel check with a descriptive error message.\n */\nexport function resolveModel(config: SerializableModelConfig, _mastra?: Mastra): MastraLanguageModel {\n  const metadataError = () => {\n    throw new Error(\n      `Model ${config.provider}/${config.modelId} is a metadata-only stub. ` +\n        `The actual model instance should be resolved from the run registry.`,\n    );\n  };\n\n  return {\n    provider: config.provider,\n    modelId: config.modelId,\n    specificationVersion: config.specificationVersion ?? 'v2',\n    supportedUrls: {},\n    doGenerate: metadataError,\n    doStream: metadataError,\n    __metadataOnly: true,\n  } as MastraLanguageModel;\n}\n\n/**\n * Reconstruct the _internal (StreamInternal) object from available state","sourceCodeStart":435,"sourceCodeEnd":471,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/durable/utils/resolve-runtime.ts#L435-L471","documentation":"resolveModel() in resolve-runtime.ts is a fallback used when the real model instance cannot be re-hydrated: it returns a metadata-only stub whose methods throw this descriptive error. Hitting it means the serialized model config (provider/modelId) was found in the run registry, but the actual MastraLanguageModel instance was never resolved from the run registry or Mastra instance.","triggerScenarios":"Resuming a durable run whose stored model config can't be mapped back to a real model — model registry miss, the provider/modelId no longer registered, or `mastra` not passed to resolveModel so no lookup is possible.","commonSituations":"Resuming runs after a deploy where model registration changed, renamed providers/models between versions, or resume code paths that lost the Mastra instance reference.","solutions":["Ensure resume/execution paths pass the Mastra instance to resolveModel so the real model can be looked up.","Re-register the model under the same provider/modelId stored in the run registry.","If a run is stale (model renamed/removed), start a new run instead of resuming it.","Check the `__metadataOnly` hint in errors 1075 — it indicates this stub was reached."],"exampleFix":"// before\nconst model = resolveModel(storedConfig);\n// after\nconst model = resolveModel(storedConfig, mastra); // resolve real instance from registry","handlingStrategy":"type-guard","validationCode":"const model = resolveModel(storedConfig, mastra);\nif ((model as any).__metadataOnly) {\n  throw new Error(`Model ${storedConfig.provider}/${storedConfig.modelId} is not registered; cannot resume run`);\n}","typeGuard":"function isRealModel(m: unknown): m is MastraLanguageModel {\n  return !!m && typeof m === 'object' && 'doStream' in m && !(m as any).__metadataOnly;\n}","tryCatchPattern":"try {\n  const model = resolveModel(config, mastra);\n  assertRealModel(model);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('metadata-only stub')) {\n    logger.error(`Model ${config.provider}/${config.modelId} not in registry — re-register or start a new run`);\n  }\n  throw e;\n}","preventionTips":["Always pass the Mastra instance to resolveModel","Keep provider/modelId registrations stable across deploys; version model registries","Before resuming old runs, verify the stored model config still maps to a registered model","Treat the __metadataOnly flag as a stop-the-line signal in custom pipelines"],"tags":["model","serialization","run-registry","resume"],"backgroundTag":"model-stub-not-resolved","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}