{"record":{"id":"d64c477c3a93133c","repo":"mastra-ai/mastra","slug":"unknowntoolprovidererror-message-e-g-unknown-too","errorCode":null,"errorMessage":"UnknownToolProviderError.message (e.g. unknown tool provider: ${providerId})","messagePattern":"UnknownToolProviderError\\.message \\(e\\.g\\. unknown tool provider: (.+?)\\)","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/tool-providers.ts","lineNumber":85,"sourceCode":"    _toolProviderModule = await import('@mastra/core/tool-provider');\n  }\n  return _toolProviderModule;\n}\n\nfunction requireEditor(editor: IMastraEditor | undefined): IMastraEditor {\n  if (!editor) {\n    throw new HTTPException(500, { message: 'Editor is not configured' });\n  }\n  return editor;\n}\n\nasync function resolveProvider(editor: IMastraEditor, providerId: string): Promise<ToolProvider> {\n  try {\n    return editor.getToolProviderOrThrow(providerId);\n  } catch (error) {\n    const { UnknownToolProviderError } = await loadToolProviderModule();\n    if (error instanceof UnknownToolProviderError) {\n      throw new HTTPException(404, { message: error.message });\n    }\n    throw error;\n  }\n}\n\n// Emit a single warn per process when the connection-owner fallback fires.\n// Multi-tenant deployments that forget to wire `mapUserToResourceId` (or\n// `MASTRA_USER_KEY`) silently funnel every `caller-supplied` pin into one\n// shared OAuth account — surface that misconfiguration once.\nlet defaultBucketWarned = false;\nfunction warnDefaultBucketFallback(logger: IMastraLogger | undefined): void {\n  if (defaultBucketWarned) return;\n  defaultBucketWarned = true;\n  logger?.warn(\n    '[tool-providers] caller-supplied scope falling back to shared \"default\" bucket — ' +\n      'wire mapUserToResourceId or set MASTRA_USER_KEY to avoid cross-tenant OAuth sharing',\n  );\n}","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/tool-providers.ts#L67-L103","documentation":"HTTP 404 raised by resolveProvider when editor.getToolProviderOrThrow(providerId) throws an UnknownToolProviderError, meaning no tool provider is registered in the Mastra editor under the given providerId. The library re-throws it as an HTTPException so the server returns 404 with the original message (e.g. 'unknown tool provider: ${providerId}'). Other errors from resolution are passed through unchanged.","triggerScenarios":"Any /api/tool-providers/:providerId/* route (schema, authorize, auth-status, connection-status, connections, disconnect) with a providerId that is not registered via editor.registerToolProvider / the Mastra config's tool providers.","commonSituations":"Typo in the providerId in client code or playground; provider registered only in a different Mastra instance/environment (dev vs prod); registration code never ran because of a config load failure; plugin/package version change renamed or removed a built-in provider id.","solutions":["Verify the exact providerId string against the ids passed to editor.registerToolProvider (or the toolProviders config) in the server instance handling the request.","Ensure the provider registration code actually executes at server startup (check for early returns/failed config loads before registration).","If the id comes from stored data (pins, saved UI state), clean up or migrate stale provider ids referencing removed providers.","Confirm the deployed environment is the one where the provider is registered."],"exampleFix":"// before\nawait fetch(`/api/tool-providers/com.githun/providers`);\n// after\nawait fetch(`/api/tool-providers/com.github/providers`); // matches registered provider id","handlingStrategy":"validation","validationCode":"const registeredIds = await api.listToolProviders();\nif (!registeredIds.includes(providerId)) {\n  throw new Error(`Provider '${providerId}' not registered; available: ${registeredIds.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await api.getProvider(providerId);\n} catch (e) {\n  if (e.status === 404 && /unknown tool provider/i.test(e.message)) {\n    // refresh provider registry / show 'provider not found' UI\n  } else throw e;\n}","preventionTips":["Keep provider ids in a single shared constants module used by both registration and client calls.","Log the registered provider ids at server startup for quick comparison.","Migrate/clean stale provider references when renaming or removing providers."],"tags":["http-404","tool-providers","server","configuration"],"backgroundTag":"unknown-provider-id","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}