What causes "Preview packages are still missing." in paperclipai/paperclip?

Run the migrator pack/publish steps (plan-migrator, pack, publish) for the SHA before invoking result.

paperclipai/paperclip · error · Error

Preview packages are still missing.

Error message

Preview packages are still missing.

What it means

The 'result' subcommand verifies that the preview's cloud image and (when PREVIEW_MIGRATOR=true) the @paperclipai/shared and @paperclipai/db npm packages exist before writing stack-deploy-result/result.json. When either migrator package is missing from the registry for the given SHA, it throws this error instead of declaring the build ready.

Solutions

Run the migrator pack/publish steps (plan-migrator, pack, publish) for the SHA before invoking result.
Re-run the publish step after waiting for npm propagation — publishing is idempotent for existing packages.
Check the earlier publish job logs for failures covering @paperclipai/shared and @paperclipai/db.
If this preview does not need the migrator, unset/fix PREVIEW_MIGRATOR so the package check is skipped.

Example fix

// before: result without migrator packages
await result(sha, requestId);
// after: publish migrator packages first
await publishPreview(sha, requestId); // includes shared/db packages
await result(sha, requestId);

Defensive patterns

Strategy: validation

Validate before calling

const ready = await imageExists(sha)
  && await packageExists('@paperclipai/shared', sha)
  && await packageExists('@paperclipai/db', sha);
if (!ready) throw new Error('Artifacts not ready; run publish steps first.');

Type guard

null

Try / catch

try {
  await result(sha, requestId);
} catch (e) {
  if (String(e.message).includes('Preview packages are still missing')) {
    console.error('Run pack/publish for @paperclipai/shared and @paperclipai/db before result.');
    process.exit(1);
  }
  throw e;
}

Prevention

Always run the full plan → pack → publish → result sequence in the workflow.
Verify PREVIEW_MIGRATOR matches whether migrator packages were actually published.
Wait for npm propagation between publish and result steps.
Check upstream publish job status before the result job runs (needs: in Actions).

When it happens

Trigger: Running `preview-artifacts.mjs result <sha> <requestId>` with PREVIEW_MIGRATOR=true in the environment while `packageExists('@paperclipai/shared', sha)` or `packageExists('@paperclipai/db', sha)` returns false — i.e. the publish step for migrator packages was skipped, failed, or has not propagated yet.

Common situations: Forgetting to run the plan-migrator/publish step before result; the migrator publish job failed earlier in the workflow; npm visibility lag right after publish; PREVIEW_MIGRATOR env var set incorrectly to 'true' on a run that never published packages.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at scripts/preview-artifacts.mjs:217

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const [command, ...args] = process.argv.slice(2);
  try {
    if (command === "plan" || command === "plan-migrator") {
      const [sha, requestId, migrator] = args;
      validateRequest(sha, requestId);
      if (process.env.GITHUB_REF !== "refs/heads/master") throw new Error("Preview workflow definitions must run from master.");
      const { image, packages } = await planArtifacts(sha, {
        image: command === "plan", migrator: command === "plan-migrator" || migrator === "true",
      });
      appendFileSync(process.env.GITHUB_OUTPUT, `image=${image}\npackages=${packages}\n`);
    } else if (command === "pack") packPreview(...args);
    else if (command === "publish") await publishPreview(...args);
    else if (command === "publish-image") await publishImage(...args);
    else if (command === "result") {
      const [sha, requestId] = args;
      validateRequest(sha, requestId);
      if (!await imageExists(sha)) throw new Error("Cloud image is still missing.");
      if (process.env.PREVIEW_MIGRATOR === "true" && !(await packageExists("@paperclipai/shared", sha) && await packageExists("@paperclipai/db", sha))) throw new Error("Preview packages are still missing.");
      mkdirSync("stack-deploy-result", { recursive: true });
      writeFileSync("stack-deploy-result/result.json", JSON.stringify({ version: 1, stage: "build", requestId, sha, status: "ready" }) + "\n");
    } else throw new Error("Expected plan, plan-migrator, pack, publish, publish-image, or result.");
  } catch (error) { console.error(error.message); process.exitCode = 1; }
}

View on GitHub (pinned to 3f1d897a7c)