mirror of
https://github.com/langgenius/dify-official-plugins.git
synced 2026-07-21 17:45:23 -04:00
I packaged and installed the plugin locally, but it doesn't work. #759
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @XUANYUANRuins on GitHub (Oct 29, 2025).
Self Checks
Dify version
v1.7.1
Plugin version
0
Cloud or Self Hosted
Self Hosted (Docker)
Steps to reproduce
I packaged and installed the plugin locally, but it doesn't work. The page redirects to a blank page and shows an error.
✔️ Error log
No response
@dosubot[bot] commented on GitHub (Oct 29, 2025):
A blank page and client-side error after installing a local plugin in Dify is often caused by issues in the plugin package itself. Based on recent fixes and common problems, here are the most likely causes and what you should check:
manifest.yaml formatting: Make sure your manifest.yaml does not have unnecessary quotes, uses
meta.version: 0.0.1, and follows the field order and structure of official plugins. Incorrect formatting can cause installation failures and frontend errors like blank pages [PR #1945].ToolProvider implementation: Your plugin provider class must implement all required methods, especially
_validate_credentials, even if your plugin does not use credentials. Missing this method can cause installation to fail and break the UI [PR #1876].Frontend error handling: If your plugin has runtime errors or is missing required fields, the Dify frontend may not catch these errors gracefully, resulting in a blank page. The browser console will show the exact error—please check it and share the stack trace for more targeted help.
Backend logs: Check your Docker container logs for any errors related to plugin installation or loading. These logs can reveal backend validation or runtime issues that aren't visible in the UI.
If you update your manifest and provider code to match the latest official plugin standards and still see the blank page, please provide the browser console error message and any relevant backend logs. This will help pinpoint the root cause.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 29, 2025):
I also encountered issues when debugging the plugin. After starting it locally with python -m main, it throws an error, even though the key and host have been configured correctly.
@dosubot[bot] commented on GitHub (Oct 29, 2025):
The errors you're seeing—
BrokenPipeErrorandBlockingIOErrorin gevent's socket code—are common when the plugin server tries to write to a socket that's already closed or unavailable. This often happens if the client (Dify or the debug tool) disconnects unexpectedly, or if there's a mismatch in how the plugin server and Dify expect to communicate during local debugging. These errors can loop if the server keeps trying to write after the socket is gone.This is a known pain point when running
python -m mainto debug Dify plugins locally, especially if the.envor debug connection settings aren't exactly right, or if the server isn't handling socket closure gracefully. You can see a nearly identical traceback and discussion in this issue.To troubleshoot:
.envsettings (especiallyINSTALL_METHOD,REMOTE_INSTALL_HOST,REMOTE_INSTALL_PORT, andREMOTE_INSTALL_KEY) and make sure they match what Dify expects for remote debugging.If you can share the exact
.envand command sequence, or any logs from the Dify side, it may help pinpoint the handshake or connection step that's failing.To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 29, 2025):
I have run the server in localhost, but it still throw exception.
@dosubot[bot] commented on GitHub (Oct 29, 2025):
The repeated
BrokenPipeErrorandBlockingIOErroryou’re seeing are a known issue when running a Dify plugin server locally with remote installation settings. This usually means the plugin server is trying to write to a socket that’s already closed—often because the Dify main app closed the connection or the handshake failed. This can happen even if your.envmatches the Dify web UI, as the problem is often with the underlying socket protocol or network setup, not just the config values [reference].Common causes include: the Dify main app not being fully up or reachable at the specified IP/port, Docker network isolation (try using your LAN IP or
host.docker.internalinstead oflocalhost), or a mismatch in how the plugin server and Dify expect to communicate during debugging. Also, make sure your plugin’s provider class implements all required methods (especially_validate_credentials), and yourmanifest.yamlmatches the latest format—missing these can cause blank pages and runtime errors [reference].If you’ve checked all config and the error persists, try running both Dify and your plugin outside Docker (if possible) to rule out network issues, and check the Dify backend logs for handshake or connection errors. If you can share the full traceback and any Dify logs from the connection attempt, it may help pinpoint the exact failure.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 29, 2025):
when I change "INSTALL_METHOD=remote" to "INSTALL_METHOD=local" ,console log is
why?
@dosubot[bot] commented on GitHub (Oct 29, 2025):
When you set
INSTALL_METHOD=local, the plugin runs in a mode where it doesn't try to connect to the main Dify app over the network. Instead, it starts up locally, logs a confirmation that the agent is installed, and then enters a loop where it emits heartbeat events—these are just periodic health checks to show the process is alive, even if there's no active session or external connection. That's why you see the agent installation log followed by repeated heartbeat logs with null session IDs and empty data.In contrast,
INSTALL_METHOD=remotetries to establish a TCP connection and handshake with the Dify main app, which can lead to socket errors if the connection fails or is closed. The heartbeat mechanism in local mode is a simple keep-alive signal and is expected behavior in this setup.This pattern is also seen in other offline or air-gapped environments using local mode, where the plugin just keeps itself alive and ready for requests, without needing to maintain a network connection to Dify. Reference
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 29, 2025):
it means that If I want to debug my plugin, I must set the parameter to ‘’INSTALL_METHOD=remote‘’.？
@XUANYUANRuins commented on GitHub (Oct 30, 2025):
The previous issue has been temporarily resolved, but I've encountered a new problem. I tried adding a selector in agent-strategies. Although the plugin starts successfully, selecting this strategy on the UI redirects to an error page.
step:
step1~3:
step 4:
The function_calling.yaml :
What did I write wrong? How should I fix it?
@dosubot[bot] commented on GitHub (Oct 30, 2025):
This kind of UI error is usually caused by a misconfiguration or schema mismatch in your function_calling.yaml, especially for selector-type parameters. Dify's frontend does not handle YAML or schema errors gracefully—if the selector parameter is missing required fields, has an unexpected structure, or uses unsupported types, the UI can crash or redirect to an error page instead of showing a helpful message (source).
For selector parameters, make sure your YAML matches the format used in official plugins. A typical selector parameter should look like this:
Common mistakes include: missing the
type: selectorfield, not providingoptionsas a list of objects with bothlabelandvalue, or omittingrequired,label, ordescription. Also, ensure all YAML indentation is correct and there are no stray tabs or spaces.If your YAML matches this structure and you still get the error, check the browser console for a more specific error message—it may point to the exact field or value causing the problem. Also, make sure your plugin and Dify are both up to date, as there have been fixes for parameter handling and validation in recent versions (source).
If you share the full content of your function_calling.yaml and any browser console errors, I can help pinpoint the exact issue.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 30, 2025):
Browser Console throw a exception:
function_calling.yaml
@dosubot[bot] commented on GitHub (Oct 30, 2025):
The
TypeError: e.show is undefinedin the Dify UI when selecting your agent-strategy is almost always caused by a schema or data mismatch in your function_calling.yaml—especially with selector-type parameters. Dify's frontend expects every selector parameter to have a specific structure: each option must be an object with both alabel(with all required languages) and avalue, and the parameter itself must includetype: selector,required,label, andoptionsfields. Missing or misformatted fields will cause the UI to crash instead of showing a helpful error.Recent Dify frontend updates have made the UI more strict about undefined or missing fields in agent-strategy schemas, especially for selector parameters and output schemas. If your YAML is missing any required field, or if an option is not structured as expected, you'll get this kind of error (reference).
Double-check your function_calling.yaml against the official agent-strategy examples. Make sure every selector option is an object with both
labelandvalue, and that all required fields are present and correctly indented. If you still see the error, check your browser console for which parameter or field is undefined—this will point you to the exact schema mismatch.If you want, paste the full contents of your function_calling.yaml here and I can help spot the exact issue.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 30, 2025):
identity:
name: function_calling
author: Dify
label:
en_US: FunctionCalling
zh_Hans: FunctionCalling
pt_BR: FunctionCalling
description:
en_US: Function Calling is a basic strategy for agent, model will use the tools provided to perform the task.
zh_Hans: Function Calling 是一个基本的 Agent 策略，模型将使用提供的工具来执行任务。
pt_BR: Function Calling is a basic strategy for agent, model will use the tools provided to perform the task.
features:
parameters:
type: model-selector
scope: tool-call&llm
required: true
label:
en_US: Model
zh_Hans: 模型
pt_BR: Model
type: array[tools]
required: true
label:
en_US: Tool list
zh_Hans: 工具列表
pt_BR: Tool list
type: string
required: true
label:
en_US: Instruction
zh_Hans: 指令
pt_BR: Instruction
auto_generate:
type: prompt_instruction
template:
enabled: true
type: any
scope: array[object]
required: false
label:
en_US: Context
zh_Hans: 上下文
pt_BR: Context
type: select
required: false
label:
en_US: Context-Handler
zh_Hans: 上下文处理
pt_BR: Context-Handler
placeholder:
en_US: Select a context-handler
zh_Hans: 选择上下文处理策略
options:
en_US: test1
zh_Hans: 测试1
value: test1
en_US: test2
zh_Hans: 测试2
value: test2
show_on:
default: test1
type: string
required: true
label:
en_US: Query
zh_Hans: 查询
pt_BR: Query
type: number
required: true
label:
en_US: Maximum Iterations
zh_Hans: 最大迭代次数
pt_BR: Maximum Iterations
default: 3
max: 30
min: 1
extra:
python:
source: strategies/function_calling.py
@dosubot[bot] commented on GitHub (Oct 30, 2025):
The UI error happens because your YAML uses
type: selectfor thecontext_handlerparameter, but Dify expectstype: selectorfor dropdown/selectors in agent-strategy parameters. Also, each option should be an object with both a top-levellabel(with all required languages) and avalue. The frontend and backend strictly enforce this schema—if the type or options are misformatted, the UI will crash with errors likeTypeError: e.show is undefinedsource.Here's how to fix your YAML:
Make sure the rest of your parameters follow the same strict schema. This should resolve the frontend error and allow you to select your agent-strategy in the UI source.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@XUANYUANRuins commented on GitHub (Oct 30, 2025):
"type: selector" will cause an error; "type: select" is the correct one.
@dosubot[bot] commented on GitHub (Oct 30, 2025):
You're correct—"type: select" is the right value for dropdown parameters in Dify agent-strategy YAMLs. The codebase and official examples confirm that "select" is supported, while "selector" is not recognized and will cause errors in both the backend and frontend. For reference, see the parameter type definitions in the Dify codebase, which include "select" but not "selector" (source).
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
