{"record":{"id":"30837a18fb160bac","repo":"n8n-io/n8n","slug":"models-couldn-t-be-loaded-check-that-the-selected","errorCode":null,"errorMessage":"Models couldn't be loaded. Check that the selected credential is valid and has the required permissions, then try again.","messagePattern":"Models couldn't be loaded\\. Check that the selected credential is valid and has the required permissions, then try again\\.","errorType":"exception","errorClass":"UserError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/ai-utilities/src/model-discovery/request.ts","lineNumber":19,"sourceCode":"import { UserError } from 'n8n-workflow';\n\nimport type { ListModelsFn, ListModelsOptions, ProviderModel } from './types';\n\n/** GET a provider endpoint and parse JSON, treating rejected credentials as user errors. */\nexport async function getJson(\n\turl: string,\n\theaders: Record<string, string>,\n\toptions: ListModelsOptions,\n\tprovider: string,\n): Promise<unknown> {\n\tconst fetchFn = options.fetch ?? globalThis.fetch;\n\tconst response = await fetchFn(url, {\n\t\tmethod: 'GET',\n\t\theaders: { ...headers, ...options.headers },\n\t});\n\tif (!response.ok) {\n\t\tif (response.status === 401 || response.status === 403) {\n\t\t\tthrow new UserError(\n\t\t\t\t\"Models couldn't be loaded. Check that the selected credential is valid and has the required permissions, then try again.\",\n\t\t\t\t{ shouldReport: false },\n\t\t\t);\n\t\t}\n\n\t\tconst body = await response.text().catch(() => '');\n\t\tthrow new Error(\n\t\t\t`Failed to list ${provider} models (status ${response.status})${body ? `: ${body.slice(0, 500)}` : ''}`,\n\t\t);\n\t}\n\treturn await response.json();\n}\n\n/** Resolve the API base: caller override or the provider default, without a trailing slash. */\nexport function baseUrl(options: ListModelsOptions, fallback: string): string {\n\treturn (options.baseURL ?? fallback).replace(/\\/+$/, '');\n}\n","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/ai-utilities/src/model-discovery/request.ts#L1-L37","documentation":"When listing a provider's models, the shared request helper treats HTTP 401/403 specially: the credential used for the request is missing, invalid, or lacks permission to call the models endpoint, so it throws a UserError (shouldReport:false) with an actionable message instead of a raw status. This routes the failure to the user as a configuration problem, not a telemetry-worthy bug.","triggerScenarios":"The credential selected for the chat model / agents feature has an expired/revoked API key; the key is correct but lacks the models:list scope; the wrong credential type is bound to the node; OAuth token refresh failed silently.","commonSituations":"API key revoked or rotated but not updated in n8n credentials; an Org/enterprise key without model-listing permission; OAuth credential whose token expired; copy-paste error introduced whitespace into the key.","solutions":["Open the credential in n8n and re-enter/refresh the API key or re-authorize OAuth, then retry.","Confirm the credential has permission to call the provider's /models endpoint (some scopes restrict it).","Verify the credential type matches the provider (e.g. don't bind an OpenAI key to the Anthropic node)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { UserError } from '@n8n/utils/error';\nfunction isModelAuthError(e: unknown): boolean {\n  return e instanceof UserError && /Models couldn't be loaded/.test(e.message);\n}","tryCatchPattern":"try {\n  await listModelsForProvider(provider, opts);\n} catch (e) {\n  if (e instanceof UserError && /Models couldn't be loaded/.test(e.message)) {\n    // prompt user to fix the credential, then retry\n  } else throw e;\n}","preventionTips":["Validate credentials with a test call before populating the model dropdown.","Surface this as a configuration error to the user, not a telemetry event (shouldReport is already false).","For OAuth credentials, ensure token refresh works before listing models."],"tags":["model-discovery","credentials","auth","user-error"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}