{"record":{"id":"afe56b50272aee00","repo":"remix-run/react-router","slug":"there-was-a-problem-extracting-the-file-from-the-p","errorCode":null,"errorMessage":"There was a problem extracting the file from the provided template.  Template filepath: `${tarballPath}`  Destination directory: `${destPath}`  ${error}","messagePattern":"There was a problem extracting the file from the provided template\\.  Template filepath: `(.+?)`  Destination directory: `(.+?)`  (.+?)","errorType":"exception","errorClass":"CopyTemplateError","httpStatus":null,"severity":"error","filePath":"packages/create-react-router/copy-template.ts","lineNumber":157,"sourceCode":"  throw new CopyTemplateError(\n    \"The provided template is not a valid local directory or tarball.\",\n  );\n}\n\nconst pipeline = promisify(stream.pipeline);\n\nasync function extractLocalTarball(\n  tarballPath: string,\n  destPath: string,\n): Promise<void> {\n  try {\n    await pipeline(\n      fs.createReadStream(tarballPath),\n      gunzip(),\n      tar.extract(destPath, { strip: 1 }),\n    );\n  } catch (error: unknown) {\n    throw new CopyTemplateError(\n      \"There was a problem extracting the file from the provided template.\" +\n        `  Template filepath: \\`${tarballPath}\\`` +\n        `  Destination directory: \\`${destPath}\\`` +\n        `  ${error}`,\n    );\n  }\n}\n\ninterface TarballDownloadOptions {\n  debug?: boolean;\n  filePath?: string | null;\n  token?: string;\n}\n\nasync function downloadAndExtractRepoTarball(\n  repo: RepoInfo,\n  destPath: string,\n  options: TarballDownloadOptions,","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/remix-run/react-router/blob/6beaca39526d5716c3c112ebb0782765baa5a9ce/packages/create-react-router/copy-template.ts#L139-L175","documentation":"extractLocalTarball() streams the local .tar.gz through gunzip-maybe and tar-fs into the destination directory via stream.pipeline; this error wraps any failure in that pipeline. The original error text is appended to the message, which tells you whether it was a gzip error (file not actually gzip-compressed), a tar parse error (corrupt archive), or a filesystem error (permissions, missing destination).","triggerScenarios":"A file named *.tar.gz that is actually a renamed zip or plain tar; a tarball truncated by an interrupted download; an unwritable or deleted destination directory; disk-full conditions while extracting.","commonSituations":"Manually renaming archives to .tar.gz without converting them; partial downloads; tarballs produced on Windows with non-gzip compression; restricted OS temp directories.","solutions":["Verify the file is really gzip: 'file template.tar.gz' should report 'gzip compressed data'","Verify integrity: 'tar -tzf template.tar.gz' should list entries without errors","Re-create the tarball from the source directory: tar -czf template.tar.gz -C template-dir .","Check write permissions and free space on the destination volume"],"exampleFix":"# before: renamed zip fails\nmv template.zip template.tar.gz\nnpx create-react-router my-app --template ./template.tar.gz\n\n# after: real gzip tarball\ntar -czf template.tar.gz -C template .\nnpx create-react-router my-app --template ./template.tar.gz","handlingStrategy":"try-catch","validationCode":"import { execSync } from \"node:child_process\";\n\nfunction verifyLocalTarball(p: string): void {\n  // Lists entries; non-zero exit means corrupt or not gzip\n  execSync(`tar -tzf ${JSON.stringify(p)}`, { stdio: \"pipe\" });\n}","typeGuard":null,"tryCatchPattern":"try {\n  await copyTemplate(tarballPath, dest, { onError: (e) => { throw e; } });\n} catch (e) {\n  if (e instanceof CopyTemplateError && /problem extracting/.test(e.message)) {\n    // The original cause is appended to the message\n    const cause = /gzip/.test(e.message) ? \"not gzip data\"\n      : /tar/.test(e.message) ? \"corrupt archive\"\n      : /EACCES|permission/i.test(e.message) ? \"destination not writable\"\n      : \"truncated tarball\";\n    console.error(`Extraction failed (${cause}); re-create with tar -czf`);\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Generate template tarballs with tar -czf template.tar.gz -C dir . in CI so format is guaranteed","Run tar -tzf as a smoke check in the template publish pipeline","Never rename archives to .tar.gz — convert them"],"tags":["cli","template","tarball","extraction"],"backgroundTag":"archive-extraction-failed","analyzedSha":"6beaca39526d5716c3c112ebb0782765baa5a9ce","analyzedAt":"2026-08-18T18:04:14.938Z","contentChangedAt":"2026-08-18T18:04:14.938Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}