What causes "Expected build, validate, verify-install, publish, or verify." in paperclipai/paperclip?

Run with one of the supported subcommands: build, validate, verify-install, publish, or verify.

paperclipai/paperclip · error · Error

Expected build, validate, verify-install, publish, or…

Error message

Expected build, validate, verify-install, publish, or verify.

What it means

The cloud-migrator-artifacts.mjs CLI entrypoint dispatches exactly five subcommands (build, validate, verify-install, publish, verify); any other first argument hits the else branch and throws this message. It is a CLI usage guard, not a data validation failure.

Solutions

Run with one of the supported subcommands: build, validate, verify-install, publish, or verify.
Check argument order: `node scripts/cloud-migrator-artifacts.mjs <command> <directory> <sha>` (verify takes only the sha).
Inspect the dispatch block at scripts/cloud-migrator-artifacts.mjs:203-208 for the current command set if the script was updated.

Example fix

// before
node scripts/cloud-migrator-artifacts.mjs upload ./artifacts <sha>
// after
node scripts/cloud-migrator-artifacts.mjs publish ./artifacts <sha>

Defensive patterns

Strategy: validation

Validate before calling

const COMMANDS = ["build","validate","verify-install","publish","verify"];
if (!COMMANDS.includes(process.argv[2])) {
  console.error(`Usage: node scripts/cloud-migrator-artifacts.mjs <${COMMANDS.join("|")}> <dir> <sha>`);
  process.exit(2);
}

Type guard

const isCommand = (v) => ["build","validate","verify-install","publish","verify"].includes(v);

Try / catch

try {
  await runCommand(cmd, dir, sha);
} catch (error) {
  if (/^Expected build, validate/.test(error.message)) printUsageAndExit(2);
  throw error;
}

Prevention

Wrap the script in a higher-level entry that validates argv before dispatch
Keep a usage/help subcommand so mistakes print usage instead of an error
Check CI step definitions when renaming commands

When it happens

Trigger: Running `node scripts/cloud-migrator-artifacts.mjs <unknown-cmd> ...` with a misspelled, empty, renamed, or omitted subcommand as process.argv[2].

Common situations: Typos like `--build` or `Build`; forgetting the command entirely (`node scripts/cloud-migrator-artifacts.mjs ./dir <sha>`); CI wrappers passing an option where the command belongs; assuming a `check` or `upload` alias exists.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/b77105e735b85792. Report an issue: GitHub.

Appendix: source

Thrown at scripts/cloud-migrator-artifacts.mjs:208

    aws(["put-object", "--key", objectKey, "--body", path.resolve(directory, file), "--content-type", contentType,
      "--cache-control", "public,max-age=31536000,immutable", "--if-none-match", "*"]);
  };
  for (const name of names) upload(`${name}.tgz`, prefix + manifest.packages[name].url.slice(`${artifactBase}/`.length), "application/gzip");
  upload("package-lock.json", prefix + manifest.lockfile.url.slice(`${artifactBase}/`.length), "application/json");
  // Publish the commit marker last; readers can never observe a partial bundle.
  upload("manifest.json", key, "application/json");
  return verifyVisible();
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const [command, directory, sha] = process.argv.slice(2);
  try {
    if (command === "build") buildBundle(directory, sha);
    else if (command === "validate") validateBundle(directory, sha);
    else if (command === "verify-install") verifyInstall(directory, sha);
    else if (command === "publish") await publishBundle(directory, sha);
    else if (command === "verify") await verifyPublished(directory);
    else throw new Error("Expected build, validate, verify-install, publish, or verify.");
  } catch (error) { console.error(error.message); process.exitCode = 1; }
}

View on GitHub (pinned to 3f1d897a7c)