AvaloniaUI/Avalonia · error · TypeError

Unable to create item in the requested directory

Error message

Unable to create item in the requested directory

What it means

Thrown (as TypeError) by StorageItem.createFile when the target item is not a directory or has no handle. Creating a file requires a FileSystemDirectoryHandle to call getFileHandle(name, {create:true}); a file item or a handleless well-known placeholder is not a valid parent.

Source

Thrown at src/Browser/Avalonia.Browser/webapp/modules/storage/storageItem.ts:102

                LastModified: file.lastModified,
                Type: file.type
            };
        } catch {
            return null;
        }
    }

    public static getItemsIterator(item: StorageItem): any | null {
        if (item.kind !== "directory" || !item.handle) {
            return null;
        }

        return (item.handle as any).entries();
    }

    public static async createFile(item: StorageItem, name: string): Promise<any | null> {
        if (item.kind !== "directory" || !item.handle) {
            throw new TypeError("Unable to create item in the requested directory");
        }

        await item.verifyPermissions("readwrite");
        // The file should be truncated when it is created.
        const fileHandle = await ((item.handle as any).getFileHandle(name, { create: true }) as Promise<any>);
        const writable = await fileHandle.createWritable({ keepExistingData: false });
        await writable.close();
        return fileHandle;
    }

    public static async getFile(item: StorageItem, name: string): Promise<any | null> {
        if (item.kind !== "directory" || !item.handle) {
            return null;
        }

        await item.verifyPermissions("read");

        return await ((item.handle as any).getFileHandle(name) as Promise<any>);

View on GitHub (pinned to 11c5427268)

Solutions

1. Ensure item.kind === 'directory' and item.handle is set before createFile.
2. Resolve well-known directories to real handles before creating children.
3. Use getFolder/createFolder to obtain the directory handle first.

Example fix

// before
const child = await StorageItem.createFile(fileItem, 'notes.txt'); // fileItem is a file

// after
if (item.kind !== 'directory' || !item.handle) throw new TypeError('parent must be a directory');
const child = await StorageItem.createFile(item, 'notes.txt');

if (item.kind !== 'directory' || !item.handle) {
  throw new TypeError('createFile requires a directory parent with a handle');
}

function isDirectoryItem(item: StorageItem): boolean {
  return item.kind === 'directory' && !!item.handle;
}

try { return await StorageItem.createFile(item, name); }
catch (e) {
  if (e instanceof TypeError && /create item/.test(e.message)) { /* resolve a directory handle first */ return null; }
  throw e;
}

When it happens

Trigger: StorageItem.createFile(item, name) where item.kind !== 'directory' or item.handle is undefined. Calling createFile on a file StorageItem or on createWellKnownDirectory result without a resolved handle.

Common situations: Passing a file handle as the parent directory; using a well-known directory placeholder whose handle was never materialized; polyfill mode where the directory handle is absent.

Related errors

• StorageItem is not a file
• StorageItem is not a writeable file
• Unable to move item to the requested directory
• Permissions denied
• Unable to access .NET memory

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/14dbb29253aa9996. Report an issue: GitHub.