laurent22/joplin · error · Error

Unsupported file system entity type: ${header.type}

Error message

Unsupported file system entity type: ${header.type}

What it means

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.

Source

Thrown at packages/app-mobile/utils/fs-driver/tarExtract.ts:48

			throw new Error(`Extracting ${outPath} would overwrite`);
		}

		// Allows moving to the next item after all data for this entry has been read
		// **and** this data has been processed.
		// See https://github.com/laurent22/joplin/issues/10285
		const streamEndPromise = new Promise<void>((resolve) => {
			stream.once('end', () => resolve());
		});

		if (header.type === 'directory') {
			await fsDriver.mkdir(outPath);
		} else if (header.type === 'file') {
			const parentDir = dirname(outPath);
			await fsDriver.mkdir(parentDir);

			await fsDriver.appendBinaryReadableToFile(outPath, stream);
		} else {
			throw new Error(`Unsupported file system entity type: ${header.type}`);
		}

		// Drain the rest of the stream.
		stream.resume();
		await streamEndPromise;
		next();
	});

	let finished = false;
	const finishPromise = new Promise<void>((resolve, reject) => {
		extract.once('finish', () => {
			finished = true;
			resolve();
		});

		extract.once('error', (error) => {
			reject(error);
		});

View on GitHub (pinned to 2654b33620)

Solutions

1. 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.
2. If symlinks are expected, extend tarExtract's switch to handle 'symlink' by copying the link target as a regular file.
3. Inspect header.type in the error message to identify the exact entry, then remove or convert that file in the source before re-archiving.

Example fix

// before
} else {
	throw new Error(`Unsupported file system entity type: ${header.type}`);
}
// after — handle symlinks by copying target as a regular file
} else if (header.type === 'symlink') {
	const parentDir = dirname(outPath);
	await fsDriver.mkdir(parentDir);
	await fsDriver.copy(resolve(cwd, header.linkname), outPath);
} else {
	throw new Error(`Unsupported file system entity type: ${header.type}`);
}

// Before creating the archive, filter to regular files + dirs only
const { lstatSync } = require('fs');
const filter = (f) => {
  const s = lstatSync(f);
  return s.isFile() || s.isDirectory();
};
// pass `filter` to tar.create

function isSupportedTarType(t) { return t === 'file' || t === 'directory'; }

try {
  await tarExtract(options);
} catch (e) {
  if (/Unsupported file system entity type/.test(e.message)) {
    // log the type, rebuild archive without symlinks/devices, retry
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error! Destination already exists
• tarExtract: Source file does not exist
• Extracting ${outPath} would overwrite
• No model found at path: ${JSON.stringify(modelFolderPath)}
• Model not found at path ${modelPath}

AI-assisted analysis of laurent22/joplin@2654b33620 (2026-08-12). Data as JSON: /api/errors/91b003c9fca613f9. Report an issue: GitHub.