Fixing Chrome’s “Cannot load extension with file or directory name _metadata” error on macOS

Chrome extension zip fails on macOS due to hidden __MACOSX folder. Learn how to fix the "_metadata" error effectively.

Cannot load extension with file or directory name _metadata. Filenames starting with “_” are reserved for use by the system.

If you develop Chrome extensions on macOS you have probably seen this message the first time you zipped your Chrome extension folder and tried to reload or publish in Chrome Web Store the extension.

The wording makes you think Chrome is suddenly rejecting your perfectly valid _locales directory (if you have it), but the real culprit is a hidden folder macOS added behind your back: __MACOSX.

What is actually happening

1. In Finder, you right-click your extension folder and choose Compress.
2. macOS (at least in macOS Tahoe 26.1 / 25B78) creates YourExtension.zipand adds a hidden __MACOSX folder.
3. Inside __MACOSX are Apple-specific resource-fork files (._filename) that store Finder metadata.
4. When Chrome unpacks the archive-locally or through the Chrome Web Store uploader, it finds directories or files starting with _ (underscore), and rejects the extension with the misleading _metadata error.

The error message is therefore misleading:

Chrome is not complaining about _locales (if you have it), it is complaining about the foreign __MACOSX directory.

Quick solution

Open the ZIP file, delete the __MACOSX folder, save it again, and Chrome will load it normally.

Note: Re-zip isn’t needed because modern macOS lets you delete directly inside the ZIP.

Better Solution (recommended)

Use the command-line zipper and tell it to skip AppleDouble files:

cd ~/path/to/your/extension   # root folder that contains manifest.json
zip -r ../my-extension.zip . -x ".*" -x "__MACOSX/*"

• -r mean recursive
• -x ".*" mean ignore hidden files such as .DS_Store
• -x "__MACOSX/*" mean ignore the resource-fork folder

This ensures you zip exactly what Chrome expects and nothing extra. Chrome loads it without any _metadata complaint.

Side note: the real _metadata folder

If you ever use Chrome’s Pack extension… button or unzip a .crx file you will see a folder called _metadata.

That folder contains the extension’s public-key signature and is meant only for distribution, not for development.

If you try to load an unpacked extension that still includes the _metadata folder, Chrome triggers the same error message. Delete it before using Load unpacked.

This is why the error message is so confusing and Chrome uses the same wording for two unrelated scenarios.