langgenius/dify · error · ValueError

Invalid UUID format in tag_ids.

Error message

Invalid UUID format in tag_ids.

What it means

Raised by AppListBaseQuery.validate_tag_ids when at least one stripped item fails uuid.UUID() construction. The validator normalizes every item to a stringified UUID; any malformed value re-raises as 'Invalid UUID format in tag_ids.' inside a Pydantic ValidationError.

Source

Thrown at api/controllers/console/app/app.py:122

    is_created_by_me: bool | None = Field(default=None, description="Filter by creator")

    @field_validator("tag_ids", mode="before")
    @classmethod
    def validate_tag_ids(cls, value: list[str] | None) -> list[str] | None:
        if not value:
            return None

        if not isinstance(value, list):
            raise ValueError("Unsupported tag_ids type.")

        items = [str(item).strip() for item in value if item and str(item).strip()]
        if not items:
            return None

        try:
            return [str(uuid.UUID(item)) for item in items]
        except ValueError as exc:
            raise ValueError("Invalid UUID format in tag_ids.") from exc

    @field_validator("creator_ids", mode="before")
    @classmethod
    def validate_creator_ids(cls, value: list[str] | None) -> list[str] | None:
        if not value:
            return None

        if not isinstance(value, list):
            raise ValueError("Unsupported creator_ids type.")

        items = [str(item).strip() for item in value if item and str(item).strip()]
        if not items:
            return None

        try:
            return [str(uuid.UUID(item)) for item in items]
        except ValueError as exc:
            raise ValueError("Invalid UUID format in creator_ids.") from exc

View on GitHub (pinned to ef8544b173)

Solutions

1. Use the full canonical UUID (e.g., 550e8400-e29b-41d4-a716-446655440000) returned by the tag list endpoint.
2. Fetch valid tag IDs first via GET /console/apps/tags and select from those.
3. Strip whitespace and verify format client-side before sending.
4. Reject empty or partial strings in the UI before submit.

Example fix

// before
const ids = tags.map(t => t.name);

// after
const ids = tags.map(t => t.id); // full UUID from GET /apps/tags

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
function filterValidUuids(ids) { return (ids || []).filter((id) => UUID_RE.test(id)); }

const isUuid = (v) => typeof v === 'string' && UUID_RE.test(v);

try { await axios.get('/apps', { params }); }
catch (e) { if (/Invalid UUID format in tag_ids/.test(e.message)) params.tag_ids = filterValidUuids(params.tag_ids); }

When it happens

Trigger: Passing a non-UUID string in tag_ids (slug, integer, name, partial UUID, UUID with wrong hyphenation). Common with copy-paste of tag slugs instead of tag IDs.

Common situations: Frontend stores tag names instead of tag IDs; URL-encoding mangles the UUID; partial UUID copied from the UI; tag IDs from a different environment that uses different identifiers.

Related errors

• Invalid UUID format in creator_ids.
• Unsupported tag_ids type.
• Unsupported creator_ids type.
• tracing_provider is required when enabled is True
• Unsupported query list type.

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/564cf1f1cf30218b. Report an issue: GitHub.