{"record":{"id":"51b5199192488527","repo":"nocobase/nocobase","slug":"swagger-get-returned-404-check-the-base-url-and","errorCode":null,"errorMessage":"`swagger:get` returned 404. Check the base URL and enable the `API documentation plugin` if needed.","messagePattern":"`swagger:get` returned 404\\. Check the base URL and enable the `API documentation plugin` if needed\\.","errorType":"http","errorClass":null,"httpStatus":404,"severity":"error","filePath":"packages/core/cli/src/lib/bootstrap.ts","lineNumber":269,"sourceCode":"  role?: string,\n  context: {\n    envName?: string;\n    commandToken?: string;\n  } = {},\n  options: {\n    allowEnableApiDoc?: boolean;\n    retryAppAvailability?: boolean;\n    quiet?: boolean;\n  } = {},\n) {\n  let response =\n    options.retryAppAvailability === false\n      ? 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...');","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/nocobase/nocobase/blob/fa42722fefe44265490dff2c27d79e2882bce4fa/packages/core/cli/src/lib/bootstrap.ts#L251-L287","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\nnb doc --quiet            # 404, plugin disabled\n// after (enable plugin first)\ncurl -X POST \"http://localhost:13000/pm:enable?filterByTk=api-doc\"\nnb doc --quiet","handlingStrategy":"validation","validationCode":"const res = await fetch(`${baseUrl.replace(/\\/+$/, '')}/swagger:get`);\nif (res.status === 404) {\n  throw new Error('API documentation plugin disabled or wrong baseUrl — enable `api-doc` first.');\n}","typeGuard":"function isSwaggerAvailable(res: { status: number }): boolean {\n  return res.status !== 404;\n}","tryCatchPattern":"try {\n  await nb(['doc', '--quiet']);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('swagger:get` returned 404')) {\n    console.error('Enable the API documentation plugin or fix the baseUrl, then retry.');\n  } else throw error;\n}","preventionTips":["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."],"tags":["cli","http-404","plugin","swagger"],"backgroundTag":"endpoint-404-not-found","analyzedSha":"fa42722fefe44265490dff2c27d79e2882bce4fa","analyzedAt":"2026-09-01T00:54:31.202Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}