Troubleshooting
Uploads
| Message | Fix |
|---|---|
| couldn't find .claude-plugin/plugin.json (a plugin) or SKILL.md (a skill) at the top of the zip | Zip the skill or plugin folder itself, so SKILL.md or .claude-plugin/ is at the top (one wrapping folder is fine). |
| SKILL.md frontmatter needs a "name" | Add a name: line to the --- block at the top of SKILL.md. |
| SKILL.md frontmatter needs a "description" | Add a description: line to the --- block at the top of SKILL.md. Claude uses it to decide when to load the skill. |
| this is a marketplace, not a plugin | Upload each plugin on its own. |
| refusing unsafe path in zip | The zip contains a path that escapes its folder (../…) or is absolute. Re-zip from the folder. |
| refusing symlink in zip / encrypted zips are not accepted | Replace links with the real files; don't password-protect the zip. |
| …is larger than… / too many files | See the limits in the overview. |
| binary files (images, documents, …) total more than 4MB | Shrink or remove large images and documents, or host them elsewhere and link to them. |
| this exact … is already in the queue | The same content was already submitted — open the existing one. |
| "waxell-placeholder" is a reserved name | Rename the skill or plugin. |
Scanning
| You see | Means |
|---|---|
| Waiting for the security scan… | The scan is running; it usually takes a few seconds. |
| The security scan never ran | No result came back within 15 minutes. It's in review; click Rescan to try again. |
| The scan failed | The scanner returned an error. It's in review; Rescan to try again. |
An older submission may say Binary files were dropped from this upload: it was uploaded before binary files were kept, so they won't ship. Upload it again.
Repository sync
The status line in Settings → Approved marketplace, step 2, shows the last error.
| Error | Fix |
|---|---|
| the token was rejected — check it hasn't expired or been revoked | Create a new token and update it with Edit. |
| the token can't do this — it needs write access to the repository | GitHub: Contents: Read and write. GitLab: api scope, Developer role or higher. |
| the token can read but not push | As above — the token needs write access. |
| repository or branch not found | Check the repository path and branch, and that the token was granted that repository. |
| the stored access token couldn't be read | Reconnect with Edit and a fresh token. |
Sync now is always safe: it compares the repository with what's approved and commits only the difference.
An approval doesn't appear in claude.ai
Check, in order:
- Waxell committed it. The status line shows In sync and a recent commit; open the commit link.
- claude.ai synced it. In claude.ai, open the marketplace — Last synced should show that commit. If not, click Re-sync, and check Sync automatically is on.
- It's visible. A new marketplace's Default access is Not available. Set it to Available to install or Installed by default — see Set who sees it.
Claude Code doesn't show a plugin
- Claude Code 2.1.224 or later is required.
- The plugin must be Approved in Waxell.
- Plugins installed from other marketplaces stop working once the lockdown block is applied — that's intended.