> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common issues and fixes for building, packaging, debugging, and installing Dify plugins

## Package and Install

### Why does `dify plugin package` fail with `plugin_unique_identifier is not valid`?

The `author` field in `manifest.yaml` and any `provider/*.yaml` file must match your GitHub handle. Update it in every file, repackage with `dify plugin package`, and reinstall.

### Why am I seeing `plugin verification has been enabled, and the plugin you want to install has a bad signature`?

Self-hosted Dify enforces signature verification on plugin packages by default. You have two options:

1. **Recommended for production**: sign your package. See [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification).
2. **For development and trusted internal use**: disable verification. Add `FORCE_VERIFYING_SIGNATURE=false` to `docker/.env`, then restart:

   ```bash theme={null}
   cd docker
   docker compose down
   docker compose up -d
   ```

   This allows installing any unsigned plugin, including ones outside the Marketplace, so only do this in environments you control.

### Is there a maximum size for a `.difypkg` file?

Yes. The plugin daemon rejects packages over a configurable limit (default `50MB`). If you ship large model weights or static assets, host them externally and download on first use, or contact Dify support about raising the limit for marketplace plugins.

### My plugin needs Python 3.13. Can I change the runtime?

No. Plugins run inside a managed Python 3.12 environment. Pin your dependencies to versions compatible with 3.12. The daemon does not honor a different runtime version in `manifest.yaml`.

## Remote Debugging

### Why does my plugin start but never appear in the workspace?

Three things to check, in order: (1) the daemon log shows an incoming registration, (2) the `REMOTE_INSTALL_KEY` matches what's shown in the debug dialog, (3) `REMOTE_INSTALL_URL` uses the `host:port` format (not separate variables). See [Plugin Debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) for the full troubleshooting list.

### Do my code changes hot-reload?

No. Stop the plugin process with `Ctrl+C` and rerun `python -m main` after every change.

## OAuth and Credentials

### What callback URL should I configure with the upstream OAuth provider?

Use `https://<your-dify-host>/console/api/oauth/plugin/<author>/<plugin-name>/tool/callback` for tool plugins, replacing `tool` with `datasource` or `trigger` for those plugin types. The exact pattern is shown in your plugin's OAuth setup card inside Dify.

### Why are my OAuth tokens not refreshing?

The plugin SDK refreshes tokens automatically when they expire, provided your provider implementation returns a valid `refresh_token` from the initial authorization. Confirm `OAuthCredentials.refresh_token` is populated, and that your `_oauth_refresh_credentials` method is implemented.

## Marketplace Publishing

### Why was my Marketplace PR rejected by the automated check?

The reviewer runs a 12-check pre-flight on every PR. The most common failures:

* **`author` in `manifest.yaml` contains `langgenius` or `dify`**: reserved for first-party plugins; use your own GitHub handle.
* **`dify_plugin` SDK pin is below `0.5.0`**: bump the pin in `requirements.txt`.
* **`README.md` contains Chinese characters**: move translations to `readme/README_zh_Hans.md` (see [Multilingual README](/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme)).
* **PR title or body contains Chinese**: only the bilingual notice line is allowlisted; everything else must be English.
* **Missing `PRIVACY.md` or `_assets/`**: both are required, and `PRIVACY.md` must be non-empty.
* **Version is already published**: bump `version` in `manifest.yaml` before re-submitting.

The full list of checks lives in [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace#reviewer-checklist).

### How long does the Marketplace review take?

PRs to `langgenius/dify-plugins` are typically reviewed within a few business days. PRs that haven't seen reviewer activity in 14–30 days are marked stale; respond on the PR to reset that timer.

### How do I publish an update for a plugin already on the Marketplace?

Bump `version` in `manifest.yaml`, open a new PR against `langgenius/dify-plugins` with the new package. The Marketplace shows the new version once merged. See [Auto-publish PR](/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr) for the GitHub Action that automates this.

### Can I monetize my plugin?

Not currently. The Marketplace only accepts free plugins. Future pricing policies will be announced separately.

## Storage and Limits

### Where do plugin logs go?

Self-hosted: container logs of the plugin daemon (`docker compose logs plugin_daemon`). Cloud: visible in the workspace's plugin debug panel during remote debugging only; persisted logs are not exposed in the UI. Use [Plugin Logging](/en/develop-plugin/features-and-specs/plugin-types/plugin-logging) for structured output.

### Is plugin storage scoped per workspace?

Yes. The KV storage API (`self.session.storage`) is isolated per workspace per plugin install. Two workspaces using the same plugin do not share keys. See [Persistent Storage (KV)](/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv).