Release Breaking Changes#

Catalog of critical backward-incompatible changes in Dify that require operator action during upgrades. Standard flask upgrade-db / docker compose up is not sufficient for these; they each require additional manual steps. 1

Upgrade checklist (any major version): (1) flask upgrade-db, (2) flask backfill-plugin-auto-upgrade, (3) verify plugin daemon image tag matches the Dify release, (4) remove stale plugin version directories from PLUGIN_INSTALLED_PATH.

model_type Enum Rename — 1.14.x#

Affected versions: Any instance upgrading to 1.14.0 or later with pre-existing model provider records.

Dify 1.14.x renamed model_type column values in the PostgreSQL dify database without running a data migration against existing rows 2:

The rename mapping is codified in legacy_model_type_migration.py. The application-level code change is tracked in PR #34488 and the database fix landed in PR #36520.

Symptoms 3:

• UI shows "Credentials unavailable" on all pre-configured model providers
• Browser console shows HTTP 400 "Credential with id … not found"
• Model deletions appear to succeed but records reappear on refresh
• Inference still works — only management operations (view, edit, delete) are broken

Fix#

Versions with Alembic migration 2026_08_27_1200-5578e028b2f2 and later (PR #41326):

flask db upgrade applies the fix automatically. The migration service canonicalizes legacy values across all five affected tables (provider_models, provider_model_credentials, tenant_default_models, provider_model_settings, load_balancing_model_configs), resolves duplicate-key collisions deterministically (newest row wins), and rotates the provider cache namespace to v2 to invalidate stale cached credentials. 4

The CLI command for an online migration (before or after DB upgrade) is available via api/commands/data_migrate.py:

# Dry-run first (default)
docker compose exec api flask data-migrate legacy-model-types

# Apply (requires --apply flag)
docker compose exec api flask data-migrate legacy-model-types --apply

Older versions or manual fix:

Back up affected tables, then run against the dify database 5:

-- Repeat for each of: provider_models, provider_model_credentials,
-- tenant_default_models, provider_model_settings, load_balancing_model_configs
UPDATE <table> SET model_type = 'llm' WHERE model_type = 'text-generation';
UPDATE <table> SET model_type = 'text-embedding' WHERE model_type = 'embeddings';
UPDATE <table> SET model_type = 'rerank' WHERE model_type = 'reranking';

tenant_default_models edge case: If the UPDATE throws SQLSTATE 23505 (duplicate key on (tenant_id, model_type)), delete the stale legacy-valued row first: 6

DELETE FROM tenant_default_models
  WHERE tenant_id = '<id>' AND model_type IN ('text-generation','embeddings','reranking');

After the SQL fix, uninstall and reinstall affected model plugins to ensure plugin state is consistent. 7

SSRF Proxy Deny-by-Default — 1.15.0#

Affected versions: Upgrades from any version < 1.15.0 where workflows or HTTP-request nodes call non-marketplace URLs (including internal/private endpoints).

As of 1.15.0, the Squid SSRF proxy enforces a deny-by-default policy. Previously, outbound HTTP requests from workflow nodes passed through with far fewer restrictions. The proxy now blocks all RFC-1918/private IP ranges and all destinations except .marketplace.dify.ai by default. 8

See docker/ssrf_proxy/squid.conf.template for the full ACL list.

Symptoms 9:

• Workflow HTTP-request nodes return 403 Forbidden
• Worker logs show: Request to URL <url> failed on attempt 1: 403 Forbidden
• ssrf_proxy container logs show: TCP_DENIED/403 for blocked destinations
• ToolSSRFError: Access to '<url>' was blocked by SSRF protection in stack traces 10

Fix#

Add allowlist exceptions via .env and restart the proxy 11:

Example .env additions:

SSRF_PROXY_ALLOW_PRIVATE_DOMAINS=internal.mycompany.com,ollama
SSRF_PROXY_ALLOW_PRIVATE_IPS=10.10.5.42,192.168.1.0/24

Then restart:

docker compose restart ssrf_proxy
# or for full config regeneration:
docker compose down && docker compose up -d

docker/ssrf_proxy/docker-entrypoint.sh reads these variables at startup and generates Squid ACL fragments into /etc/squid/dify_allow_private.conf, which is evaluated before the deny rules.

Other Known Upgrade Issues#

Plugin daemon version lockstep: The plugin daemon must be kept in version lockstep with the Dify API. Protocol mismatches cause complete communication failure. Known pairings 15:

The upgrade checklist is repeated above in the intro block for quick reference. See the Plugin Daemon Architecture KB 16 for full details on daemon version synchronization and troubleshooting.

Key References#