> ## 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 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](/en/develop-plugin/publishing/marketplace-listing/submit-plugin-to-marketplace#after-you-submit) 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](/en/develop-plugin/publishing/marketplace-listing/submit-plugin-to-marketplace#choose-the-submission-type).

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