{"record":{"id":"7da4d178c9cb441f","repo":"nocobase/nocobase","slug":"failed-to-enable-the-api-documentation-plugin-vi","errorCode":null,"errorMessage":"Failed to enable the `API documentation plugin` via `pm:enable`.\n${JSON.stringify(enableResponse.data, null, 2)}","messagePattern":"Failed to enable the `API documentation plugin` via `pm:enable`\\.\n(.+?)","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/cli/src/lib/bootstrap.ts","lineNumber":282,"sourceCode":"      ? await requestJson(getSwaggerUrl(baseUrl), { token, role })\n      : await waitForSwaggerSchema(baseUrl, token, role, { quiet: options.quiet });\n\n  if (response.status === 404) {\n    if (options.allowEnableApiDoc === false || options.quiet) {\n      throw new Error('`swagger:get` returned 404. Check the base URL and enable the `API documentation plugin` if needed.');\n    }\n\n    printInfo('The API documentation plugin is not enabled.');\n    const shouldEnable = await confirmEnableApiDoc();\n    if (!shouldEnable) {\n      throw new Error('`swagger:get` returned 404. Enable the `API documentation plugin` first.');\n    }\n\n    const enableUrl = `${baseUrl.replace(/\\/+$/, '')}/pm:enable?filterByTk=api-doc`;\n    printVerbose(`Enabling API documentation plugin via ${enableUrl}`);\n    const enableResponse = await requestJson(enableUrl, { method: 'POST', token, role });\n    if (!enableResponse.ok) {\n      throw new Error(\n        `Failed to enable the \\`API documentation plugin\\` via \\`pm:enable\\`.\\n${JSON.stringify(enableResponse.data, null, 2)}`,\n      );\n    }\n\n    updateTask('Enabled the API documentation plugin. Waiting for application readiness...');\n    await waitForServiceReady(baseUrl, token, role);\n    response = await waitForSwaggerSchema(baseUrl, token, role);\n  }\n\n  if (!response.ok) {\n    throw new Error(formatSwaggerSchemaError(response, { baseUrl, token, ...context }));\n  }\n\n  return (response.data?.data ?? response.data) as any;\n}\n\nfunction collectErrorEntries(data: any) {\n  if (Array.isArray(data?.errors)) {","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/nocobase/nocobase/blob/fa42722fefe44265490dff2c27d79e2882bce4fa/packages/core/cli/src/lib/bootstrap.ts#L264-L300","documentation":"After the user agrees, fetchSwaggerSchema POSTs to `<baseUrl>/pm:enable?filterByTk=api-doc` to enable the API documentation plugin. If that request returns a non-ok response, the CLI throws this error including the pretty-printed response body (enableResponse.data) so the server-side reason (auth failure, plugin missing, dependency error) is visible.","triggerScenarios":"The pm:enable call fails — typically 401/403 because the provided token/role lacks plugin-management permission, 404 because the api-doc plugin package is not installed in that deployment, or 500 from a server-side enable error (missing dependencies, failed install).","commonSituations":"Using a token from a role without admin/pm permissions; commercial deployment where the api-doc plugin is not bundled; server error while installing/enabling the plugin (npm registry unreachable on the server); token expired mid-flow.","solutions":["Inspect the JSON body in the error for status/message; fix the server-side cause it reports.","Use a token/role with plugin-management (admin) permission and retry.","Verify the api-doc plugin is installed in the deployment; install/upgrade the NocoBase instance if the package is absent.","Enable the plugin manually in the Plugin Manager UI, then rerun the original command."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const res = await fetch(`${baseUrl.replace(/\\/+$/, '')}/pm:enable?filterByTk=api-doc`, {\n  method: 'POST',\n  headers: { authorization: `Bearer ${token}` },\n});\nif (!res.ok) throw new Error(`Pre-check: cannot enable api-doc plugin (${res.status})`);","typeGuard":"function canEnablePlugins(res: { ok: boolean; status: number }): boolean {\n  return res.ok || (res.status !== 401 && res.status !== 403);\n}","tryCatchPattern":"try {\n  await nb(['doc']);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('Failed to enable the `API documentation plugin`')) {\n    console.error('Check pm:enable response body in error; usually permissions or missing plugin package.');\n  } else throw error;\n}","preventionTips":["Use an admin token/role with plugin-management permissions for CLI doc flows.","Confirm the api-doc plugin package is installed in the deployment.","Enable the plugin via the Plugin Manager UI as a fallback when pm:enable fails.","Refresh tokens before long-running flows to avoid mid-flow auth expiry."],"tags":["cli","plugin","http-error","permissions","swagger"],"backgroundTag":"plugin-enable-failed","analyzedSha":"fa42722fefe44265490dff2c27d79e2882bce4fa","analyzedAt":"2026-09-01T00:54:31.202Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}