Troubleshooting
Most of what goes wrong with Prefab is a permission macOS has not been asked for yeta permission it has not been given yet, or a piece of the app that is not running. This page covers the ones that come up, and what each one actually means.
Finder's right-click menu has no Prefab item
macOS keeps every Finder extension switched off until you turn it on, and no app is allowed to turn its own on. Open Prefab's settings (⌘,Ctrl+,), go to General ▸ Finder Extension, click Open Extension Settings, and tick Prefab in the list that appears.
If Prefab is not in that list at all, macOS has not registered the extension. It registers one when it sees the app containing it, so move Prefab into your Applications folder, open it once, and look again.
If you keep more than one copy of Prefab around, one in Applications, one in Downloads, one in the Trash, the extension Finder loads is the one belonging to the registered copy. Keep a single copy in Applications and the question stops arising.
The right-click menu has no Prefab item
Explorer caches its menus, so a newly installed Prefab may not appear until Explorer restarts. Signing out and back in does it, as does ending Windows Explorer from Task Manager, which restarts it on its own.
If it is still missing, Prefab's own registration has not been picked up. Open Prefab once and close it, then right-click again.
Windows 11 has two right-click menus. Prefab appears in the main one. On Windows 10, and under Show more options on Windows 11, it is in that list instead - the same item, drawn by the older menu.
The menu is there, but says "No templates available"
The extension reads your templates from a container it shares with the app, which is written when Prefab saves a template. Open Prefab, make sure at least one template exists, then try the menu again.
A template in the right-click menu says "Could Not Read Template"
The extension decodes templates by itself, so a copy of the extension older than the app can meet a template using something it has never heard of. Quit Prefab and open it again so FinderFile Explorer picks up the matching version. If it keeps happening, check that the copy in your Applications folder is the current one, because that is the copy FinderFile Explorer loads the menu from.
A deploy fails with a permission error
Prefab is sandboxed and can only write where you have pointed it. When a deploy names a folder it has not been given, it shows Permission Required. Grant Access opens a folder picker already at that location, and the deploy carries on by itself once you confirm. Cancelling leaves everything as it was, with nothing half-created.
This mostly happens to deploys that arrive with a path already decided: a prefab://deploy link
with path=, or FinderFile Explorer's right-click menu. Choosing a location in the Create Here panel grants
access as part of choosing it.
Grant the parent folder rather than each project folder, since everything inside a granted folder is covered by it. Settings ▸ Permissions lists what Prefab currently has.
A terminal command does not seem to run
Work through these in order, in Settings ▸ Permissions ▸ Terminal Access.
- Terminal commands may be switched off. There is a single switch for them. Each experience sets its own starting position, and only Developer starts with them on.
- The shell runner may not be installed. A sandboxed app can only run commands through a small script in your Application Scripts folder. If the status reads Not installed, click Install Shell Runner and confirm the save panel. Setup required means writing it failed, and Open Scripts Folder shows you where it was meant to go.
- The installed script may be out of date. The line under the status names the version you have and the version this build of Prefab expects. If they differ, click Update Shell Runner.
- Test it. With the runner installed, Test runs a real command and reports what came back, including its exit code.
macOS never tells an app whether a command it launched succeeded, only whether it started.A command's exit status is reported directly here. The current runner sends the exit code back as its last line of output. A runner installed before that could not, so Prefab treated every command as having worked. If commands seem to run without effect and nothing is ever reported as failing, update the runner first.
A command hangs, or is reported as timed out
Every terminal action carries a Timeout in seconds, 300 by default. A command that overruns it is stopped along with anything it started, and reported as having timed out rather than as a mysterious failure. Set the timeout to 0 to wait indefinitely, which is worth doing only for something you know is slow and safe.
Timeouts are enforced by the shell runner, so an installed script older than version 3 ignores them. The version line in Settings says which you have.
Note that a failing command stops the rest of that item's deploy actions unless Continue on error is switched on for it. See Terminal commands.
A watched folder is not doing anything
Prefab has to be running. Watching stops when the app quits. Keep Keep running in menu barKeep running when the window closes switched on in Settings ▸ General so closing the window leaves Prefab running. When it next starts, it catches up on whatever arrived while it was gone.
The folder may be paused. The menu barnotification area icon lists every watched folder under Watching, with Pause Watching and Resume Watching on each.
The file may still be arriving. Prefab waits until a file has finished landing before touching it:
- An iCloud file that has not been downloaded yet is skipped, because there is nothing on disk to work on.
- A file that reports download progress is left alone until it reports being finished.
- Temporary names such as
.crdownloadand.partare ignored. The real file arrives under its own name a moment later. - A file that is still empty counts as unfinished.
- Otherwise Prefab waits for the file's size to stop changing for two seconds.
Hidden files and lock files, which is anything starting with a dot and Office's ~$ files, are
never acted on at all.
The file may already have been handled. A file Prefab has processed is marked, so it is not renamed or moved twice. It is looked at again when the folder's rules change, or when a rule is set to Also when a file is edited.
The rules may not be the ones you edited a moment ago. A watched folder keeps the copy of the rules it was given when it was deployed, so that a folder made months ago keeps naming files the way it always has. To hand it the edited rules, deploy the template over that same folder again, which replaces the registration.
To sweep a folder by hand, use Apply Rules to Existing Files… from the menu barnotification area. It shows exactly what it would do and waits for you to confirm. See Managing and undoing.
A watched folder has disappeared from the Watching list
A folder that has been deleted or moved to the Trash stops being watched on its own, and Prefab drops it from the list rather than counting a folder that is not there.
A folder on a drive that is merely unplugged, or a network share that has gone away, keeps its rules and its history and starts working again when it comes back.
A .prefab file will not import
The message says which of these it is.
- That isn't a Prefab template file - the file does not end in
.prefab. Renaming something else to.prefabwill not make it one. - This template was made with a newer version of Prefab - the file's format is newer than the Prefab reading it. Update Prefab on this MacPC.
- Could not read '…' - the file may be damaged - the archive could not be opened, or its manifest could not be read. Usually a transfer that did not finish, so get the file again or export it again.
- That file doesn't contain any templates - the archive opened, but held nothing to import.
If the import succeeds and reports that some files could not be read, the templates are fine but those entries will deploy as empty files. Either way, nothing already in your library is changed by an import. See Sharing templates.