{"record":{"id":"7a749aeaa034cdd4","repo":"nocobase/nocobase","slug":"missing-required-output-path-output","errorCode":null,"errorMessage":"Missing required output path --output","messagePattern":"Missing required output path --output","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/cli/src/lib/api-client.ts","lineNumber":396,"sourceCode":"      ? await createMultipartBody(options.flags, options.operation)\n      : await parseBody(options.flags, options.operation);\n  if (body !== undefined && options.operation.requestContentType !== 'multipart/form-data') {\n    headers.set('content-type', 'application/json');\n  }\n\n  const url = new URL(`${normalizeBaseUrl(baseUrl)}${requestPath}`);\n  query.forEach((value, key) => url.searchParams.append(key, value));\n\n  const response = await fetchWithPreservedAuthRedirect(url.toString(), {\n    method: options.operation.method.toUpperCase(),\n    headers,\n    body: body === undefined ? undefined : body instanceof FormData ? body : JSON.stringify(body),\n  });\n\n  if (options.operation.responseType === 'binary') {\n    const outputPath = options.flags.output;\n    if (!outputPath) {\n      throw new Error('Missing required output path --output');\n    }\n    return parseBinaryResponse(response, outputPath);\n  }\n\n  return parseResponse(response);\n}\n\nexport async function executeRawApiRequest(options: RawRequestOptions) {\n  const { baseUrl, token } = await resolveServerRequestTarget(options);\n\n  const headers = new Headers();\n  headers.set(CLI_REQUEST_SOURCE_HEADER, CLI_REQUEST_SOURCE_VALUE);\n  if (token) {\n    headers.set('authorization', `Bearer ${token}`);\n  }\n  if (options.role) {\n    headers.set('x-role', options.role);\n  }","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/nocobase/nocobase/blob/fa42722fefe44265490dff2c27d79e2882bce4fa/packages/core/cli/src/lib/api-client.ts#L378-L414","documentation":"Operations declared with `responseType: 'binary'` return a file, not JSON. The CLI writes the raw response to the path given via `--output`; if that flag is missing it throws this error instead of attempting to parse binary data as text.","triggerScenarios":"Calling a binary-download operation (e.g. export or file download endpoint) without `--output`, such as `nb api export` where options.flags.output is undefined.","commonSituations":"Treating a download endpoint like a JSON one; forgetting --output in scripts; assuming output redirects to stdout instead of a file.","solutions":["Add `--output <path>` to the command, e.g. `nb api export --output ./dump.xlsx`","Confirm the operation is actually binary (responseType in the spec); if it should return JSON, use the correct operation","In scripts, always pass a writable file path for binary endpoints"],"exampleFix":"// before\nnb api app:export --token $TOKEN\n// after\nnb api app:export --token $TOKEN --output ./backup.tar.gz","handlingStrategy":"validation","validationCode":"// before calling a binary operation\nif (operation.responseType === 'binary' && !flags.output) {\n  throw new Error('This operation downloads a file; pass --output <path>');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await executeApiRequest(options);\n} catch (err) {\n  if (err instanceof Error && err.message === 'Missing required output path --output') {\n    console.error('Binary responses must be written to a file: add --output ./result.bin');\n  } else throw err;\n}","preventionTips":["Always pair binary endpoints (exports, downloads) with --output","Choose a writable path and ensure the parent directory exists","In scripts, derive the output path from a validated variable","Check the spec's responseType to know which operations need --output"],"tags":["cli","binary-output","validation"],"backgroundTag":"missing-required-cli-argument","analyzedSha":"fa42722fefe44265490dff2c27d79e2882bce4fa","analyzedAt":"2026-09-01T00:54:31.202Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}