fix(api): tolerate legacy service_api end-user type on load

[manan-tech]

Summary

Fixes #38201.

v1.15.0 renamed the EndUserType enum value from service_api (underscore) to service-api (hyphen) and shipped the 4f7b2c8d9a10_normalize_legacy_end_user_type migration to rewrite existing rows.

However, if an end_users row still holds the legacy service_api value — the migration hasn't been run yet, or a row was created by an old instance during the upgrade window — the column's EnumText type deserializes it via EndUserType(value):

# api/models/types.py — EnumText.process_result_value
return self._enum_class(value)   # EndUserType("service_api") -> ValueError

That raises 'service_api' is not a valid EndUserType, which surfaces as HTTP 400 on every request for that end user (e.g. POST /v1/chat-messages). The reporter had to hand-fix it with SQL.

Fix

Add a _missing_ handler to EndUserType that maps the legacy service_api value to SERVICE_API, exactly mirroring the existing CreatorUserRole._missing_ (which tolerates the legacy end-user value) in the same file. Unmigrated end users then load gracefully instead of hard-failing.

• Only the exact legacy string service_api is tolerated; all other unknown values still raise.
• No schema or migration change; the canonical persisted value remains service-api.

Tests

Added to api/tests/unit_tests/models/test_end_user_type.py:

• legacy service_api and canonical service-api both resolve to EndUserType.SERVICE_API
• unknown values still raise ValueError
• EnumText.process_result_value("service_api", ...) (the actual column load path that failed) returns EndUserType.SERVICE_API

uv run python -m pytest tests/unit_tests/models/test_end_user_type.py → 9 passed. ruff and pyrefly clean.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran ruff (lint) and pyrefly (type-check) on the changed files plus the focused unit tests — all pass.

From Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01JBVXLzDtt5GcRQeJfStmUw

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	51.87%	51.86%	-0.00%
Strict coverage	51.39%	51.38%	-0.00%
Typed symbols	31,536	31,536	0
Untyped symbols	29,540	29,543	+3
Modules	2952	2952	0

[QuantumGhost]

Generally speaking, you should run database migration before upgrading Dify application.

[wylswz]

Generally speaking, you should run database migration before upgrading Dify application.

When performing rolling update, the legacy enum values held by old replicas could still be committed after the migration.

[QuantumGhost]

Generally speaking, you should run database migration before upgrading Dify application.

When performing rolling update, the legacy enum values held by old replicas could still be committed after the migration.

Agreed, this is a valid rolling-update concern.

AFAIK, most data migrations are not currently designed or implemented with full rolling-upgrade compatibility in mind. Ideally, the safer release sequence should be:

1. Introduce an application-level compatibility patch before adding the data migration.
2. Introduce the database migration.
3. Ship a release that includes both the migration and the compatibility patch.
4. Remove the compatibility patch in a subsequent release.

That should address the rolling-update case.

There is still one remaining edge case: if a Dify instance upgrades across multiple versions at once, it may skip the intermediate compatibility window. For that case, I think we should either require users to upgrade version by version, or recommend stopping traffic while performing a multi-version upgrade.