How to Debug Plugin Download Failures in Dify: A Complete Troubleshooting Guide

To debug plugin download failures in Dify, enable verbose curl output in the plugin_repackaging.sh script to expose the underlying HTTP error, then validate the generated Marketplace or GitHub URL manually to identify 404s, authentication issues, or network timeouts.

Dify plugins are distributed as .difypkg archives that the platform fetches from the Dify Marketplace, GitHub releases, or local filesystems. When you need to debug plugin download failures in Dify, understanding the download architecture in plugin_repackaging.sh is essential for identifying whether the issue stems from incorrect parameters, network connectivity, or repository authentication.

Understanding the Plugin Download Architecture

The plugin_repackaging.sh script in the junjiem/dify-plugin-repackaging repository handles three distinct download sources. Each source uses a dedicated function that constructs a specific URL pattern and streams the archive using curl.

Marketplace Downloads (the market() function)

The market() function (lines 28‑52 of plugin_repackaging.sh) constructs a download URL following the pattern:

https://marketplace.dify.ai/api/v1/plugins/<author>/<name>/<version>/download

The function uses curl with the -L flag to follow redirects and saves the output to a temporary path. If the HTTP status is not 200, the script exits with the error message: "Download failed, please check the plugin author, name and version."

GitHub Release Downloads (the github() function)

The github() function (lines 54‑82) normalizes repository names and downloads release assets. It accepts either a short owner/repo format or a full GitHub URL, then constructs:

https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>.difypkg

Like the marketplace function, it relies on curl -L and aborts on non‑zero exit codes with the message: "Download failed, please check the github repo, release title and assets name."

Local File Handling (the _local() function)

The _local() function (lines 84‑97) bypasses network operations entirely. It resolves the supplied filesystem path and forwards it directly to the repackager, making it useful for debugging when you suspect network issues rather than packaging errors.

Common Causes of Plugin Download Failures in Dify

When you debug plugin download failures in Dify, the symptoms usually fall into one of the following categories. Use this reference to map error symptoms to root causes.

Symptom	Likely Cause	Verification Command
404 or 403 from Marketplace	Incorrect author, plugin name, or version; plugin not published.	curl -I https://marketplace.dify.ai/api/v1/plugins/<author>/<name>/<version>/download
404 from GitHub	Release tag or asset name typo; private repository without authentication.	Navigate to <repo>/releases/tag/<tag> in browser or run curl -I <asset_url>
Network timeout	Firewall, VPN, or DNS resolution failure.	curl -v <URL> to observe connection attempts
SSL verification error	Outdated CA bundle or corporate MITM proxy.	Add -k to curl temporarily (debugging only)
Missing unzip utility	Script attempts to repackage before checking dependencies.	Check log for "Installing unzip …" or run which unzip
Pip download failures	Wrong platform flag (-p) or missing binary wheels.	Inspect pip download output in the repackage() step

Step-by-Step Debugging Workflow

Follow this systematic approach to isolate and resolve download failures.

Step 1: Enable Verbose Curl Output

The script hides HTTP details by default. Temporarily modify the market() or github() functions in plugin_repackaging.sh to add the -v flag:

# In market() function around line 46

curl -v -L -o "${PLUGIN_PACKAGE_PATH}" "${PLUGIN_DOWNLOAD_URL}"

# In github() function around line 76  

curl -v -L -o "${PLUGIN_PACKAGE_PATH}" "${PLUGIN_DOWNLOAD_URL}"

Alternatively, prepend the entire script with set -x to trace every command:

set -x
./plugin_repackaging.sh market myauthor myplugin 0.1.0

Step 2: Validate the Generated URL Manually

Copy the ${PLUGIN_DOWNLOAD_URL} printed in the debug output and test it independently:

# For Marketplace

curl -I https://marketplace.dify.ai/api/v1/plugins/junjiem/mcp_sse/0.0.1/download

# For GitHub

curl -I https://github.com/junjiem/dify-plugin-agent-mcp_sse/releases/download/v0.2.0/agent-mcp_sse.difypkg

A 200 OK response confirms the server is reachable; 404 or 403 indicates incorrect parameters or authentication requirements.

Step 3: Check GitHub Repository Formatting

The github() function automatically prefixes https://github.com unless the argument already contains it. Passing a full URL twice creates malformed addresses like https://github.comhttps://github.com/....

Ensure you pass either:

• Short format: owner/repo
• Full format: https://github.com/owner/repo

Step 4: Verify Asset Naming Conventions

GitHub release assets must include the .difypkg suffix. If the asset name in the release differs from the script argument, GitHub returns 404 even though the release exists.

Step 5: Inspect the Downloaded Archive

If the file downloads but subsequent steps fail, verify archive integrity:

unzip -t "$(basename "$PLUGIN_PACKAGE_PATH")"

Corrupted downloads often result from incomplete network transfers or disk space issues.

Step 6: Review CI Logs for Context

When running in GitHub Actions, examine the workflow logs for the specific step executing plugin_repackaging.sh. Search for "Download failed" and review the preceding 20 lines to identify the exact URL and HTTP status.

Practical Code Examples for Debugging Plugin Download Failures in Dify

Example 1: Debug a Marketplace Download Failure

Enable tracing temporarily to expose the exact URL and HTTP response:

# Add set -x to the market function for one execution

sed -i '28s/^/set -x\n/' plugin_repackaging.sh

# Run with intentionally invalid parameters to see the failure details

./plugin_repackaging.sh market invalidUser unknownPlugin 0.0.1

# Observe the printed PLUGIN_DOWNLOAD_URL and curl exit code

# Then verify manually:

curl -I https://marketplace.dify.ai/api/v1/plugins/invalidUser/unknownPlugin/0.0.1/download

Example 2: Verify a GitHub Asset URL Before Running the Script

Prevent malformed URLs by testing the exact path the script will generate:

REPO="junjiem/dify-plugin-agent-mcp_sse"
TAG="v0.2.0"
ASSET="agent-mcp_sse.difypkg"

# Construct the URL exactly as the github() function does (lines 54-82)

if [[ "$REPO" != https://github.com* ]]; then
    REPO="https://github.com/${REPO}"
fi
URL="${REPO}/releases/download/${TAG}/${ASSET}"

echo "Testing URL: $URL"
curl -I "$URL"

# Expected: HTTP/2 200

# If 404: Check that the release tag exists and the asset name matches exactly

Example 3: Re-run with Custom Platform and Verbose Output

When the download succeeds but pip wheel resolution fails, specify the platform and capture all output:

# Run with platform flag and redirect all output to log

./plugin_repackaging.sh -p manylinux2014_x86_64 market junjiem mcp_sse 0.0.1 2>&1 | tee debug.log

# Search for specific failure points

grep -E "(curl|Download failed|pip download|unzip)" debug.log

Summary

To effectively debug plugin download failures in Dify, remember these key strategies:

• Expose hidden errors by adding -v to the curl commands in the market() and github() functions of plugin_repackaging.sh (lines 28‑52 and 54‑82).
• Validate URLs manually using curl -I to distinguish between incorrect parameters (404) and authentication issues (403).
• Check GitHub formatting carefully—the script auto-prefixes https://github.com, so pass only owner/repo or the full URL, never both.
• Verify asset names end with .difypkg and match the release exactly, as the script constructs direct download URLs without wildcard matching.
• Inspect CI logs for the specific "Download failed" message and review preceding lines to identify the exact URL and HTTP status code.

Frequently Asked Questions

Why does the script report "Download failed" without showing the HTTP error?

The plugin_repackaging.sh script suppresses curl output by default to keep logs clean. When the command returns a non‑zero exit status (lines 46‑49 for Marketplace, 76‑79 for GitHub), it prints a generic message and aborts. To see the actual HTTP status, temporarily add the -v flag to the curl calls or prepend set -x to the script.

How do I fix a 404 error when downloading from the Dify Marketplace?

A 404 from the Marketplace endpoint (https://marketplace.dify.ai/api/v1/plugins/<author>/<name>/<version>/download) indicates the plugin metadata does not exist. Verify that the author name, plugin name, and version string match exactly what is published in the Dify Marketplace. You can test the URL directly with curl -I before running the repackaging script.

What causes "Download failed" errors for GitHub releases even when the release exists?

The github() function (lines 54‑82) constructs download URLs by combining the repository name, release tag, and asset name. Common failures include passing a full GitHub URL when the script already prefixes https://github.com (creating malformed URLs like https://github.comhttps://github.com/...), or specifying an asset name that does not include the .difypkg extension. Always verify the exact asset name listed in the GitHub release page.

How can I debug network timeouts or SSL errors during plugin downloads?

For network timeouts, run curl -v <URL> to observe DNS resolution and TCP connection attempts. If you see SSL certificate verification errors, your environment may have an outdated CA bundle or be behind a corporate MITM proxy. Temporarily add the -k flag to the curl commands in plugin_repackaging.sh to bypass SSL verification for debugging purposes only, or update your system's CA certificates to resolve the issue permanently.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}