nocobase/nocobase · error

Failed to enable the `API documentation plugin` via `pm:enab

Error message

Failed to enable the `API documentation plugin` via `pm:enable`.
${JSON.stringify(enableResponse.data, null, 2)}

What it means

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.

Source

Thrown at packages/core/cli/src/lib/bootstrap.ts:282

      ? await requestJson(getSwaggerUrl(baseUrl), { token, role })
      : await waitForSwaggerSchema(baseUrl, token, role, { quiet: options.quiet });

  if (response.status === 404) {
    if (options.allowEnableApiDoc === false || options.quiet) {
      throw new Error('`swagger:get` returned 404. Check the base URL and enable the `API documentation plugin` if needed.');
    }

    printInfo('The API documentation plugin is not enabled.');
    const shouldEnable = await confirmEnableApiDoc();
    if (!shouldEnable) {
      throw new Error('`swagger:get` returned 404. Enable the `API documentation plugin` first.');
    }

    const enableUrl = `${baseUrl.replace(/\/+$/, '')}/pm:enable?filterByTk=api-doc`;
    printVerbose(`Enabling API documentation plugin via ${enableUrl}`);
    const enableResponse = await requestJson(enableUrl, { method: 'POST', token, role });
    if (!enableResponse.ok) {
      throw new Error(
        `Failed to enable the \`API documentation plugin\` via \`pm:enable\`.\n${JSON.stringify(enableResponse.data, null, 2)}`,
      );
    }

    updateTask('Enabled the API documentation plugin. Waiting for application readiness...');
    await waitForServiceReady(baseUrl, token, role);
    response = await waitForSwaggerSchema(baseUrl, token, role);
  }

  if (!response.ok) {
    throw new Error(formatSwaggerSchemaError(response, { baseUrl, token, ...context }));
  }

  return (response.data?.data ?? response.data) as any;
}

function collectErrorEntries(data: any) {
  if (Array.isArray(data?.errors)) {

View on GitHub (pinned to fa42722fef)

Solutions

  1. Inspect the JSON body in the error for status/message; fix the server-side cause it reports.
  2. Use a token/role with plugin-management (admin) permission and retry.
  3. Verify the api-doc plugin is installed in the deployment; install/upgrade the NocoBase instance if the package is absent.
  4. Enable the plugin manually in the Plugin Manager UI, then rerun the original command.
Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch(`${baseUrl.replace(/\/+$/, '')}/pm:enable?filterByTk=api-doc`, {
  method: 'POST',
  headers: { authorization: `Bearer ${token}` },
});
if (!res.ok) throw new Error(`Pre-check: cannot enable api-doc plugin (${res.status})`);

Type guard

function canEnablePlugins(res: { ok: boolean; status: number }): boolean {
  return res.ok || (res.status !== 401 && res.status !== 403);
}

Try / catch

try {
  await nb(['doc']);
} catch (error) {
  if (error instanceof Error && error.message.includes('Failed to enable the `API documentation plugin`')) {
    console.error('Check pm:enable response body in error; usually permissions or missing plugin package.');
  } else throw error;
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/7da4d178c9cb441f. Report an issue: GitHub.