{"record":{"id":"ad6f6e26c6cbc678","repo":"paperclipai/paperclip","slug":"ref-is-only-supported-for-github-import-sources","errorCode":null,"errorMessage":"--ref is only supported for GitHub import sources.","messagePattern":"--ref is only supported for GitHub import sources\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/company.ts","lineNumber":1715,"sourceCode":"          let sourcePayload:\n            | { type: \"inline\"; rootPath?: string | null; files: Record<string, CompanyPortabilityFileEntry> }\n            | { type: \"github\"; url: string };\n          let chunkedZip: { zipBytes: Uint8Array; rootPath: string } | null = null;\n\n          const treatAsLocalPath = !isHttpUrl(from) && await pathExists(from);\n          const isGithubSource = looksLikeRepoUrl(from) || (isGithubShorthand(from) && !treatAsLocalPath);\n\n          if (isHttpUrl(from) || isGithubSource) {\n            if (!looksLikeRepoUrl(from) && !isGithubShorthand(from)) {\n              throw new Error(\n                \"Only GitHub URLs and local paths are supported for import. \" +\n                \"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.\",\n              );\n            }\n            sourcePayload = { type: \"github\", url: normalizeGithubImportSource(from, opts.ref) };\n          } else {\n            if (opts.ref?.trim()) {\n              throw new Error(\"--ref is only supported for GitHub import sources.\");\n            }\n            chunkedZip = await resolveChunkedImportZip(\n              from,\n              target === \"existing\"\n                ? EXISTING_COMPANY_CHUNKED_IMPORT_THRESHOLD_BYTES\n                : CHUNKED_IMPORT_THRESHOLD_BYTES,\n            );\n            if (chunkedZip) {\n              // Too large for one request: the zip travels as a chunked\n              // transfer, so the inline files map is never built or sent.\n              sourcePayload = { type: \"inline\", rootPath: chunkedZip.rootPath, files: {} };\n            } else {\n              const inline = await resolveInlineSourceFromPath(from);\n              sourcePayload = {\n                type: \"inline\",\n                rootPath: inline.rootPath,\n                files: inline.files,\n              };","sourceCodeStart":1697,"sourceCodeEnd":1733,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/company.ts#L1697-L1733","documentation":"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.","triggerScenarios":"Running `paperclipai company import ./local-dir --ref main` or any local path alongside `--ref <value>` where the ref trims to non-empty.","commonSituations":"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.","solutions":["Drop the --ref flag when importing a local path.","If you need a specific git ref, import from the GitHub URL instead: `paperclipai company import https://github.com/org/repo --ref <branch>`."],"exampleFix":"# before\npaperclipai company import ./local-dir --ref main\n# after\npaperclipai company import ./local-dir","handlingStrategy":"validation","validationCode":"function validateImportFlags(sourceKind: \"github\" | \"local\", ref?: string): void {\n  if (sourceKind === \"local\" && ref && ref.trim()) {\n    throw new Error(\"--ref is only valid with a GitHub URL source\");\n  }\n}","typeGuard":"function isLocalSource(v: string): boolean {\n  return !/^https?:\\/\\//i.test(v.trim());\n}","tryCatchPattern":null,"preventionTips":["Build the CLI command from a source-kind-aware helper that omits --ref for local paths.","Keep two command templates: one for GitHub sources (with --ref) and one for local (without).","Document that --ref is GitHub-only near the flag definition."],"tags":["cli","validation","import","invalid-flag-combo","git-ref"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}