paperclipai/paperclip · error · Error

--ref is only supported for GitHub import sources.

Error message

--ref is only supported for GitHub import sources.

What it means

Thrown in the local-path branch of the import flow when `--ref` is supplied. The --ref flag (a git ref like a branch/tag/sha) only applies to GitHub URL sources; a local directory has no git ref to resolve. This guard prevents an ambiguous combination.

Source

Thrown at cli/src/commands/client/company.ts:1715

          let sourcePayload:
            | { type: "inline"; rootPath?: string | null; files: Record<string, CompanyPortabilityFileEntry> }
            | { type: "github"; url: string };
          let chunkedZip: { zipBytes: Uint8Array; rootPath: string } | null = null;

          const treatAsLocalPath = !isHttpUrl(from) && await pathExists(from);
          const isGithubSource = looksLikeRepoUrl(from) || (isGithubShorthand(from) && !treatAsLocalPath);

          if (isHttpUrl(from) || isGithubSource) {
            if (!looksLikeRepoUrl(from) && !isGithubShorthand(from)) {
              throw new Error(
                "Only GitHub URLs and local paths are supported for import. " +
                "Generic HTTP URLs are not supported. Use a GitHub or GitHub Enterprise URL (https://github.com/... or https://ghe.example.com/...) or a local directory path.",
              );
            }
            sourcePayload = { type: "github", url: normalizeGithubImportSource(from, opts.ref) };
          } else {
            if (opts.ref?.trim()) {
              throw new Error("--ref is only supported for GitHub import sources.");
            }
            chunkedZip = await resolveChunkedImportZip(
              from,
              target === "existing"
                ? EXISTING_COMPANY_CHUNKED_IMPORT_THRESHOLD_BYTES
                : CHUNKED_IMPORT_THRESHOLD_BYTES,
            );
            if (chunkedZip) {
              // Too large for one request: the zip travels as a chunked
              // transfer, so the inline files map is never built or sent.
              sourcePayload = { type: "inline", rootPath: chunkedZip.rootPath, files: {} };
            } else {
              const inline = await resolveInlineSourceFromPath(from);
              sourcePayload = {
                type: "inline",
                rootPath: inline.rootPath,
                files: inline.files,
              };

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Drop the --ref flag when importing a local path.
2. If you need a specific git ref, import from the GitHub URL instead: `paperclipai company import https://github.com/org/repo --ref <branch>`.

Example fix

# before
paperclipai company import ./local-dir --ref main
# after
paperclipai company import ./local-dir

function validateImportFlags(sourceKind: "github" | "local", ref?: string): void {
  if (sourceKind === "local" && ref && ref.trim()) {
    throw new Error("--ref is only valid with a GitHub URL source");
  }
}

function isLocalSource(v: string): boolean {
  return !/^https?:\/\//i.test(v.trim());
}

When it happens

Trigger: Running `paperclipai company import ./local-dir --ref main` or any local path alongside `--ref <value>` where the ref trims to non-empty.

Common situations: Developer copies a full flag set from a GitHub-import example and reuses it for a local path; a script template that always passes --ref regardless of source type.

Related errors

• Source path or URL is required.
• Invalid --collision value. Use: rename, skip, replace
• Invalid --target value. Use: new | existing
• Target existing company requires --company-id (or context de
• Only GitHub URLs and local paths are supported for import. G

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