can1357/oh-my-pi · error · ArchiveError

Unsupported UDF-only image (no ISO 9660 volume descriptor)

Error message

Unsupported UDF-only image (no ISO 9660 volume descriptor)

What it means

The volume scan encountered UDF (Universal Disk Format) descriptors but no ISO 9660 primary or Joliet descriptor, meaning the image is a UDF-only optical/disc filesystem. This reader implements ISO 9660/Joliet only, so it throws this specific error instead of the generic 'primary volume descriptor not found'.

Source

Thrown at packages/utils/src/ar/iso.ts:300

					descriptor[89] === 0x2f &&
					[0x40, 0x43, 0x45].includes(descriptor[90]!)
				) {
					joliet = parseVolumeDescriptor(descriptor, true);
				}
				if (type === 255) {
					terminated = true;
					break;
				}
			}
			pendingOffset += ISO_SECTOR_SIZE;
			scanned += ISO_SECTOR_SIZE;
		}
		position += pending.byteLength;
		chunkSectors = Math.min(chunkSectors * 2, Math.ceil(limits.maxIndexSize / ISO_SECTOR_SIZE));
	}
	if (!primary && !joliet) {
		if (sawHighSierra) throw new ArchiveError("Unsupported High Sierra CD-ROM filesystem (not ISO 9660)");
		if (sawUdf) throw new ArchiveError("Unsupported UDF-only image (no ISO 9660 volume descriptor)");
		throw invalidIso("primary volume descriptor not found");
	}
	if (!terminated) throw invalidIso("volume descriptor terminator not found");
	if (joliet) return { ...joliet, rockRidgeRoot: primary?.root };
	return primary!;
}

function decodeIdentifier(identifier: Uint8Array, joliet: boolean): string {
	let name: string;
	if (joliet) {
		if (identifier.byteLength % 2 !== 0) throw invalidIso("Joliet identifier has an odd byte length");
		const codeUnits = new Uint16Array(identifier.byteLength / 2);
		for (let index = 0; index < codeUnits.length; index++) codeUnits[index] = readUInt16BE(identifier, index * 2);
		const chunks: string[] = [];
		for (let index = 0; index < codeUnits.length; index += 4096) {
			chunks.push(String.fromCharCode(...codeUnits.subarray(index, index + 4096)));
		}
		name = chunks.join("");

View on GitHub (pinned to 9690622007)

Solutions

Read the image with a UDF-capable tool or library (e.g. mount -t udf, libudf-based extractors) instead of the ISO reader
Re-author the content as an ISO 9660 + UDF bridge image: xorriso -as mkisofs -udf -o image.iso dir/
If the source is a live UDF filesystem you control, copy the files out and pack them into a supported archive format
Confirm with a hex dump that sector 16+ hold UDF (NSR) descriptors and no ISO 9660 'CD001' descriptor

Example fix

// before
const vol = await readIso(udfDump); // ArchiveError: Unsupported UDF-only image
// after: create ISO/UDF bridge
// $ xorriso -as mkisofs -udf -o hybrid.iso content-dir/
const vol = await readIso(hybridImage);

Defensive patterns

Strategy: fallback

Validate before calling

// scan descriptor sequence for 'CD001' (ISO) vs 'BEA01'/'NSR02'/'NSR03' (UDF)
const dec = new TextDecoder();
async function tag(file, sector) {
  const b = new Uint8Array(await Bun.file(file).slice(sector * 2048 + 1, sector * 2048 + 6).arrayBuffer());
  return dec.decode(b);
}
const t = await tag(imagePath, 16);
if (t !== 'CD001') throw new Error('not an ISO 9660 bridge image (got ' + t + ')');

Type guard

null

Try / catch

try {
  vol = await readIso(image);
} catch (err) {
  if (err instanceof ArchiveError && err.message.includes('UDF-only')) {
    return extractWithUdfTool(image); // mount -t udf / UDF-aware extractor
  }
  throw err;
}

Prevention

Prefer ISO/UDF bridge images (xorriso -udf) so ISO readers still work
Route pure UDF images (DVD/BD dumps, UDF flash drives) to a UDF reader
Check sector-16 descriptor identifiers during ingestion

When it happens

Trigger: Calling the ISO reader (readVolume via the volume/entry APIs) on a pure UDF image — e.g. DVD-Video/Blu-ray UDF 2.x dumps, or USB-stick-format UDF images — where the descriptor sequence contains only UDF descriptors (NSR02/NSR03) and no ISO 9660 descriptor.

Common situations: Reading DVD/Blu-ray dumps, UDF-formatted flash drives imaged to a file, or modern optical images authored without the usual ISO 9660 bridge (no 'dual' ISO+UDF layout).

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/e9518ac6431d829e. Report an issue: GitHub.