unoplatform/uno · error · Error

Item is of an unknown type. You cannot use it as a File!

Error message

Item ${guid} is of an unknown type. You cannot use it as a File!

What it means

Thrown by NativeStorageItem.getFile as a catch-all when the item stored under the guid is neither a File, a FileSystemFileHandle, nor a FileSystemDirectoryHandle. This indicates the registered object is an unexpected/unsupported type — getItem returned undefined or an object of an unrecognized class.

Solutions

Verify the guid exists via getItem(guid) before calling getFile, and handle undefined gracefully.
Ensure addItem was called with a valid FileSystemHandle or File object.

Example fix

// before
const file = await NativeStorageItem.getFile(guid); // unknown type → throws

// after
const item = NativeStorageItem.getItem(guid);
if (!item) {
    throw new Error(`No item registered for guid ${guid}`);
}
if (!(item instanceof File) && !(item instanceof FileSystemFileHandle)) {
    throw new Error(`Item ${guid} is not a file (${item.constructor.name})`);
}
const file = await NativeStorageItem.getFile(guid);

Defensive patterns

Strategy: validation

Validate before calling

const item = NativeStorageItem.getItem(guid);
if (!item) {
    throw new Error(`No item for guid ${guid} — register it first`);
}
await NativeStorageItem.getFile(guid);

Type guard

function isKnownStorageItem(item: unknown): boolean {
    return item instanceof File
        || item instanceof FileSystemFileHandle
        || item instanceof FileSystemDirectoryHandle;
}

Try / catch

try {
    const file = await NativeStorageItem.getFile(guid);
} catch (e) {
    if (e.message.includes('unknown type')) {
        // item is missing or unsupported — re-register or skip
    } else { throw e; }
}

Prevention

Verify getItem(guid) returns a value before calling getFile.
Only register File or FileSystemHandle objects via addItem.
Track guid lifecycle to avoid using stale/removed guids.

When it happens

Trigger: The guid passed to getFile does not exist in _guidToItemMap (getItem returns undefined), or the stored item is a non-standard object type. This can happen if the guid was never registered, was already removed, or a non-FileSystem/File object was added.

Common situations: Stale guid after the item was removed via removeItem; a guid mismatch between registration and retrieval; a polyfill or browser that returns a different object type for drag-drop items.

Related errors

AI-assisted analysis of unoplatform/uno@0418340488 (2026-08-13). Data as JSON: /api/errors/d9456e9795b93c01. Report an issue: GitHub.

Appendix: source

Thrown at src/Uno.UWP/ts/Windows/Storage/NativeStorageItem.ts:36

		public static getItem(guid: string): FileSystemHandle|File {
			return NativeStorageItem._guidToItemMap.get(guid);
		}

		public static async getFile(guid: string): Promise<File> {
			const item = NativeStorageItem.getItem(guid);

			if (item instanceof File) {
				return item as File;
			}
			if (item instanceof FileSystemFileHandle) {
				return await (item as FileSystemFileHandle).getFile();
			}
			if (item instanceof FileSystemDirectoryHandle) {
				throw new Error("Item " + guid + " is a directory handle. You cannot use it as a File!");
			}

			throw new Error("Item " + guid + " is of an unknown type. You cannot use it as a File!");
		}

		public static getGuid(item: FileSystemHandle | File): string {
			return NativeStorageItem._itemToGuidMap.get(item);
		}

		public static getInfos(...items: Array<FileSystemHandle|File>): NativeStorageItemInfo[] {
			const itemsWithoutGuids: Array<FileSystemHandle|File> = [];

			for (const item of items) {
				const guid = NativeStorageItem.getGuid(item);
				if (!guid) {
					itemsWithoutGuids.push(item);
				}
			}

			NativeStorageItem.storeItems(itemsWithoutGuids);

View on GitHub (pinned to 0418340488)