{"record":{"id":"91b003c9fca613f9","repo":"laurent22/joplin","slug":"unsupported-file-system-entity-type-header-type","errorCode":null,"errorMessage":"Unsupported file system entity type: ${header.type}","messagePattern":"Unsupported file system entity type: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/app-mobile/utils/fs-driver/tarExtract.ts","lineNumber":48,"sourceCode":"\t\t\tthrow new Error(`Extracting ${outPath} would overwrite`);\n\t\t}\n\n\t\t// Allows moving to the next item after all data for this entry has been read\n\t\t// **and** this data has been processed.\n\t\t// See https://github.com/laurent22/joplin/issues/10285\n\t\tconst streamEndPromise = new Promise<void>((resolve) => {\n\t\t\tstream.once('end', () => resolve());\n\t\t});\n\n\t\tif (header.type === 'directory') {\n\t\t\tawait fsDriver.mkdir(outPath);\n\t\t} else if (header.type === 'file') {\n\t\t\tconst parentDir = dirname(outPath);\n\t\t\tawait fsDriver.mkdir(parentDir);\n\n\t\t\tawait fsDriver.appendBinaryReadableToFile(outPath, stream);\n\t\t} else {\n\t\t\tthrow new Error(`Unsupported file system entity type: ${header.type}`);\n\t\t}\n\n\t\t// Drain the rest of the stream.\n\t\tstream.resume();\n\t\tawait streamEndPromise;\n\t\tnext();\n\t});\n\n\tlet finished = false;\n\tconst finishPromise = new Promise<void>((resolve, reject) => {\n\t\textract.once('finish', () => {\n\t\t\tfinished = true;\n\t\t\tresolve();\n\t\t});\n\n\t\textract.once('error', (error) => {\n\t\t\treject(error);\n\t\t});","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/laurent22/joplin/blob/2654b33620775080d1d59c552259d41e33dad3d2/packages/app-mobile/utils/fs-driver/tarExtract.ts#L30-L66","documentation":"Thrown inside the tar-stream entry handler when header.type is neither 'directory' nor 'file'. The extractor only materializes those two entity kinds and rejects everything else (symlink, character-device, block-device, fifo, contiguous-file, etc.) to avoid writing entities the mobile FS driver and Joplin's data model cannot represent.","triggerScenarios":"The archive contains symbolic links, hardlinks, device nodes, or other non-regular entries; the tar was produced by a tool that emits 'symlink' entries for deduplicated content; a hostile/corrupt tar includes an unknown header.type string.","commonSituations":"Backups created on desktop Linux that captured symlinks; third-party tar builders that default to symlinks for repeated files; a tampered archive probing for extraction vulnerabilities; tar-stream version change introducing a new type label.","solutions":["Rebuild the archive excluding non-regular files: use tar with --no-same-owner and avoid symlinks, or filter the source tree to regular files and directories only.","If symlinks are expected, extend tarExtract's switch to handle 'symlink' by copying the link target as a regular file.","Inspect header.type in the error message to identify the exact entry, then remove or convert that file in the source before re-archiving."],"exampleFix":"// before\n} else {\n\tthrow new Error(`Unsupported file system entity type: ${header.type}`);\n}\n// after — handle symlinks by copying target as a regular file\n} else if (header.type === 'symlink') {\n\tconst parentDir = dirname(outPath);\n\tawait fsDriver.mkdir(parentDir);\n\tawait fsDriver.copy(resolve(cwd, header.linkname), outPath);\n} else {\n\tthrow new Error(`Unsupported file system entity type: ${header.type}`);\n}","handlingStrategy":"validation","validationCode":"// Before creating the archive, filter to regular files + dirs only\nconst { lstatSync } = require('fs');\nconst filter = (f) => {\n  const s = lstatSync(f);\n  return s.isFile() || s.isDirectory();\n};\n// pass `filter` to tar.create","typeGuard":"function isSupportedTarType(t) { return t === 'file' || t === 'directory'; }","tryCatchPattern":"try {\n  await tarExtract(options);\n} catch (e) {\n  if (/Unsupported file system entity type/.test(e.message)) {\n    // log the type, rebuild archive without symlinks/devices, retry\n  }\n  throw e;\n}","preventionTips":["Build archives from regular files and directories only; exclude symlinks and device nodes.","Document supported entry types for backup producers.","Validate archive contents with tar -tvf before shipping."],"tags":["mobile","filesystem","tar","backup","symlink"],"backgroundTag":null,"analyzedSha":"2654b33620775080d1d59c552259d41e33dad3d2","analyzedAt":"2026-08-12T14:26:46.263Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}