Troubleshooting

Troubleshooting

Common issues and how to resolve them.

dist/ not found after install

The host does not run npm run build for users. If your code-based extension installs but fails to activate, make sure dist/ (or whatever main references) is committed and included in the Git tag. Run npm run build locally, commit the output, then re-tag.

Extension does not activate on command

Activation events use the full command ID (onCommand:sigma.<extensionId>.<commandId>), while contributes.commands and sigma.commands.registerCommand() use the short ID (<commandId>). A mismatch between these will silently prevent activation.

For example, if id is my-publisher.my-ext and the command is run:

• activationEvents: onCommand:sigma.my-publisher.my-ext.run
• contributes.commands[].id: run
• sigma.commands.registerCommand({ id: 'run', ... }, handler)

"type": "module" missing

API extensions that run code are loaded as ESM. If "type": "module" is missing from package.json, the host cannot import the entry point and the extension will fail at runtime with no clear error. Always include it for code-based api extensions. Theme-only API extensions that omit main do not need an entry module.

Schema validation warns on sidebar url

If you see a format: uri warning for a relative path in contributes.sidebar[].url, update the @sigma-file-manager/api package. Older schema versions incorrectly required a full URI; the field accepts relative paths like dist/embed.js.

Binary not found at runtime

If sigma.binary.getPath(id) returns null:

1. Verify the id in package.json > binaries matches the id you pass to getPath().
2. Check that the binary assets include an entry for the current platform and architecture.
3. Make sure integrity is a valid SHA-256 hash (sha256:<64-hex-chars>) matching the exact downloaded file. Re-download and recompute if the upstream release changed.

Permission denied errors

Every API namespace requires its corresponding permission in package.json > permissions. If a call throws a permission error, add the missing permission and reinstall the extension locally.

See the Manifest Reference permissions table for the full mapping.

node_modules inflates the install

Do not commit node_modules. Add it to .gitignore so it is excluded from the Git tag archive. @sigma-file-manager/api is a dev-only dependency — the host provides the runtime.

Continue

← Previous: Submitting to the Marketplace

Next: Home →