What causes "Missing required output path --output" in nocobase/nocobase?

Add `--output ` to the command, e.g. `nb api export --output ./dump.xlsx`

Missing required output path --output

Error message

Missing required output path --output

What it means

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.

Source

Thrown at packages/core/cli/src/lib/api-client.ts:396

      ? await createMultipartBody(options.flags, options.operation)
      : await parseBody(options.flags, options.operation);
  if (body !== undefined && options.operation.requestContentType !== 'multipart/form-data') {
    headers.set('content-type', 'application/json');
  }

  const url = new URL(`${normalizeBaseUrl(baseUrl)}${requestPath}`);
  query.forEach((value, key) => url.searchParams.append(key, value));

  const response = await fetchWithPreservedAuthRedirect(url.toString(), {
    method: options.operation.method.toUpperCase(),
    headers,
    body: body === undefined ? undefined : body instanceof FormData ? body : JSON.stringify(body),
  });

  if (options.operation.responseType === 'binary') {
    const outputPath = options.flags.output;
    if (!outputPath) {
      throw new Error('Missing required output path --output');
    }
    return parseBinaryResponse(response, outputPath);
  }

  return parseResponse(response);
}

export async function executeRawApiRequest(options: RawRequestOptions) {
  const { baseUrl, token } = await resolveServerRequestTarget(options);

  const headers = new Headers();
  headers.set(CLI_REQUEST_SOURCE_HEADER, CLI_REQUEST_SOURCE_VALUE);
  if (token) {
    headers.set('authorization', `Bearer ${token}`);
  }
  if (options.role) {
    headers.set('x-role', options.role);
  }

View on GitHub (pinned to fa42722fef)

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

Example fix

// before
nb api app:export --token $TOKEN
// after
nb api app:export --token $TOKEN --output ./backup.tar.gz

Defensive patterns

Strategy: validation

Validate before calling

// before calling a binary operation
if (operation.responseType === 'binary' && !flags.output) {
  throw new Error('This operation downloads a file; pass --output <path>');
}

Try / catch

try {
  await executeApiRequest(options);
} catch (err) {
  if (err instanceof Error && err.message === 'Missing required output path --output') {
    console.error('Binary responses must be written to a file: add --output ./result.bin');
  } else throw err;
}

Prevention

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

When it happens

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

Common situations: Treating a download endpoint like a JSON one; forgetting --output in scripts; assuming output redirects to stdout instead of a file.

Related errors

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