Frequently Asked Questions

​

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 Marketplace workflow runs package, metadata, dependency, disclosure, and install checks. The exact set evolves with the repository. Common blocking failures include:

• More than one .difypkg changed: submit one plugin package per PR.
• Incomplete PR template or risk selection: keep every template section, select exactly one risk level, and disclose sensitive capabilities.
• Secrets, development artifacts, or unexplained binaries: remove them from the package and rebuild it.
• Invalid manifest, README, privacy, source, or contact metadata: keep package metadata and PR claims consistent.
• Dependency policy failure: Python plugins must use dify-plugin >= 0.9.0; resolve installation and vulnerability findings.
• Duplicate version or failed install/package test: increment the version, rebuild, and test with the current daemon.

See Handle PR Checks and Review to interpret the result and decide whether you need to act.

​

How long does the Marketplace review take?

There is no guaranteed review time. Complete package evidence, a filled PR template, and resolved CI findings reduce review back-and-forth. Monitor the PR for reviewer comments and respond on the same branch.

​

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

Bump version in manifest.yaml, rebuild the package, and open a new PR against langgenius/dify-plugins with the new .difypkg. Keep previously published packages in the repository unless a maintainer asks otherwise. See Submit a Marketplace Pull Request.

​

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).