Skip to main content

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.

​
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.
  2. For development and trusted internal use: disable verification. Add FORCE_VERIFYING_SIGNATURE=false to docker/.env, then restart: 
    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 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).
  • 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.

​
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 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 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).
Edit this page | Report an issue