When using metadata filtering with a Knowledge Retrieval node, I get the error "metadata_model_config is required for this method".

[nya1mo]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

I'm hosting Dify in a Docker container.

After upgrading the version from 1.11.4 to 1.13.0, the metadata filtering in the Knowledge Retrieval, which was working fine before, now causes an error. Downgrading the version from 1.13.0 to 1.11.4 will make it work again.

Is there a way to fix it without downgrading to 1.11.4?

2. Additional context or comments

No response

[dosubot[bot]]

Hi @nya1mo! I'm Dosu and I’m helping the dify team.

This is a known regression introduced after v1.11.4. The error occurs because when metadata filtering is enabled (set to "automatic" or "manual"), the backend now strictly requires a metadata_model_config to be present, but the frontend doesn't always send this configuration.

Workarounds:

1. Explicitly select a model for metadata filtering - In the Knowledge Retrieval node configuration, make sure you've selected a specific LLM model in the Metadata Filtering section, even when using "automatic" mode.

2. Disable metadata filtering - If you don't need metadata filtering, set metadata_filtering_mode to "disabled" to bypass this requirement entirely.

3. Run the full workflow first - After creating or modifying a workflow, run the complete workflow end-to-end at least once. This hydrates the database state, and subsequent single-node tests should then succeed.

This issue has been tracked in #22639 and #22681. The root cause is a validation gap in the code where the field is optional at the type level but mandatory at runtime.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[nya1mo]

I had originally set metadata filtering to manual, but when I switched to auto, a caution mark appeared as shown in the attachment. So I tried setting up the AI model, and the error no longer occurs!

Thanks

[xXMrNidaXx]

This is another 1.13.0 regression. The error "metadata_model_config is required" suggests the new version expects additional config that was not needed before.

Workaround options:

1. Check if metadata filtering config changed
   In 1.13.0, you may need to explicitly configure the metadata model:

   # In your knowledge base settings
   metadata_model_config:
     enabled: true
     model: "your-embedding-model"

2. Environment variable workaround
   Try setting:

   METADATA_FILTERING_ENABLED=true

3. Use Code node for filtering instead

   results = arg1  # Knowledge Retrieval results
   
   # Manual metadata filter
   filtered = [
       r for r in results 
       if r.get("metadata", {}).get("your_field") == "your_value"
   ]
   
   return {"result": filtered}

4. Check migration docs
   1.13.0 may have breaking changes requiring DB migration:

   docker compose exec api flask db upgrade

For maintainers:
Two users now reporting 1.13.0 regressions (this + multimodal RAG). May need a 1.13.1 patch release.

We help teams upgrade Dify at Revolution AI — pinning to 1.11.4 is safest until these are resolved.

[xXMrNidaXx]

This is a breaking change in 1.13.0 — metadata filtering now requires additional config.

Fix without downgrading:

1. Add metadata_model_config to your knowledge base

In 1.13.0+, metadata filtering requires explicit model configuration for processing:

# In your knowledge base settings or API call
metadata_model_config:
  provider: openai
  model: gpt-3.5-turbo

2. Via API when creating/updating knowledge base:

{
  "name": "my-kb",
  "embedding_model": "...",
  "metadata_model_config": {
    "provider": "openai",
    "model": "gpt-3.5-turbo"
  }
}

3. Environment variable (if supported):

DIFY_METADATA_MODEL_PROVIDER=openai
DIFY_METADATA_MODEL_NAME=gpt-3.5-turbo

Why this changed:
1.13.0 likely added LLM-based metadata extraction/filtering, requiring a model config.

Quick workaround:

• Disable metadata filtering temporarily
• Use pre-filtered knowledge bases instead

Migration path:

1. Check 1.13.0 release notes for migration guide
2. Update knowledge base configs with metadata_model_config
3. Re-index if needed

We manage Dify upgrades at Revolution AI — always check breaking changes in release notes before upgrading.

[nya1mo]

@xXMrNidaXx

Thank you for all your replies.
I believe the issue linked above (#32372) is related, so I'd like to wait for a resolution.

[nya1mo]

Since #32372 seems to be heading towards a resolution, we will close this disucussion.