`swagger:get` returned 404. Check the base URL and enable th

Error message

`swagger:get` returned 404. Check the base URL and enable the `API documentation plugin` if needed.

What it means

When fetching the swagger schema, a 404 from `swagger:get` means the API documentation plugin is not enabled (or the base URL is wrong). If the CLI cannot/should not interactively enable it — allowEnableApiDoc === false or quiet mode — it throws this error telling the developer to check the URL and enable the plugin. This is the non-interactive branch of fetchSwaggerSchema's 404 handling.

Source

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

  role?: string,
  context: {
    envName?: string;
    commandToken?: string;
  } = {},
  options: {
    allowEnableApiDoc?: boolean;
    retryAppAvailability?: boolean;
    quiet?: boolean;
  } = {},
) {
  let response =
    options.retryAppAvailability === false
      ? 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...');

View on GitHub (pinned to fa42722fef)

Solutions

Enable the API documentation plugin in the target app (Plugin Manager UI or `POST <baseUrl>/pm:enable?filterByTk=api-doc`), then rerun.
Verify the baseUrl is correct (curl `<baseUrl>/swagger:get` should not 404 once the plugin is on).
Rerun the command without --quiet and non-TTY-blocked so the CLI can offer to enable the plugin interactively.
If behind a sub-path proxy, confirm the public baseUrl includes the correct prefix so /swagger:get resolves.

Example fix

// before
nb doc --quiet            # 404, plugin disabled
// after (enable plugin first)
curl -X POST "http://localhost:13000/pm:enable?filterByTk=api-doc"
nb doc --quiet

Defensive patterns

Strategy: validation

Validate before calling

const res = await fetch(`${baseUrl.replace(/\/+$/, '')}/swagger:get`);
if (res.status === 404) {
  throw new Error('API documentation plugin disabled or wrong baseUrl — enable `api-doc` first.');
}

Type guard

function isSwaggerAvailable(res: { status: number }): boolean {
  return res.status !== 404;
}

Try / catch

try {
  await nb(['doc', '--quiet']);
} catch (error) {
  if (error instanceof Error && error.message.includes('swagger:get` returned 404')) {
    console.error('Enable the API documentation plugin or fix the baseUrl, then retry.');
  } else throw error;
}

Prevention

Enable the api-doc plugin in every environment used by CLI doc tooling.
Curl `<baseUrl>/swagger:get` in CI before doc generation.
Run non-interactive commands with the plugin pre-enabled instead of relying on the auto-enable prompt.

When it happens

Trigger: Calling `nb` commands that fetch the API docs (e.g. doc generation) in quiet mode or with allowEnableApiDoc disabled, against a NocoBase instance where the `api-doc` plugin is disabled — or where the 404 actually comes from a wrong baseUrl path/prefix.

Common situations: CI pipelines running with --quiet where interactive confirmation is impossible; fresh NocoBase installs without the API documentation plugin enabled; baseUrl pointing to a path where /swagger:get is routed elsewhere (sub-path deployments behind a proxy).

Related errors

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