paperclipai/paperclip · error · Error

--file is required

Error message

--file is required

What it means

Thrown by uploadAsset() in cli/src/commands/client/asset.ts when the --file option is missing, empty, or whitespace-only. The check happens before any filesystem or network access, so this is a pure usage guard for `paperclipai asset upload` (and any command reusing uploadAsset).

Source

Thrown at cli/src/commands/client/asset.ts:95

            printOutput({ ok: true, out: opts.out, bytes: bytes.length }, { json: ctx.json });
            return;
          }
          process.stdout.write(bytes);
        } catch (err) {
          handleCommandError(err);
        }
      }),
  );
}

async function uploadAsset(
  apiBase: string,
  apiKey: string | undefined,
  path: string,
  opts: AssetOptions,
): Promise<unknown> {
  if (!opts.file?.trim()) {
    throw new Error("--file is required");
  }
  const bytes = await readFile(opts.file);
  const form = new FormData();
  form.set("file", new Blob([bytes], { type: inferContentTypeFromPath(opts.file) }), opts.file.split(/[\\/]/).pop() ?? "asset");
  if (opts.namespace?.trim()) form.set("namespace", opts.namespace.trim());
  if (opts.alt?.trim()) form.set("alt", opts.alt.trim());
  if (opts.title?.trim()) form.set("title", opts.title.trim());

  const response = await fetch(buildApiUrl(apiBase, path), {
    method: "POST",
    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : undefined,
    body: form,
  });
  return parseFetchResponse(response);
}

async function downloadAsset(apiBase: string, apiKey: string | undefined, assetId: string): Promise<Buffer> {
  const response = await fetch(buildApiUrl(apiBase, apiPath`/api/assets/${assetId}/content`), {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass an explicit path: `paperclipai asset upload --file ./logo.png`.
2. If using a variable, ensure it is set: `--file "${ASSET_PATH:?missing}"`.
3. Confirm the flag name is --file (not --filename/--path).

Example fix

// before
ASSET=""; paperclipai asset upload --file "$ASSET"
// after
ASSET=./logo.png; paperclipai asset upload --file "$ASSET"

function resolveAssetPath(file: string | undefined): string {
  const p = file?.trim();
  if (!p) throw new Error('--file is required (pass a path to the asset)');
  return p;
}

try { await uploadAsset(apiBase, apiKey, path, opts); }
catch (err) {
  if (err instanceof Error && err.message === '--file is required') {
    console.error('Usage: paperclipai asset upload --file <path> [--namespace ns] [--alt ...] [--title ...]');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running `paperclipai asset upload` without --file, or with --file '' / --file ' '. The guard uses opts.file?.trim(), so even an all-whitespace path is rejected.

Common situations: Forgot the flag. Shell expansion produced an empty string (e.g. --file "$MISSING_VAR”). Flag typo such as --filename.

Related errors

• Challenge secret is required. Pass --token or --token-env.
• Cannot build API path with an empty path segment.
• Invalid --include value. Use one or more of: company,agents,
• Skill reference is required unless --all is used.
• Refusing to delete without --yes

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/d3f115463da68552. Report an issue: GitHub.