infiniflow/ragflow · error · RuntimeError

Exceed the maximum length of file name!

Error message

Exceed the maximum length of file name!

What it means

RuntimeError from check_doc_health when the uploaded filename's UTF-8 byte length exceeds FILE_NAME_LEN_LIMIT. The limit is on bytes, not characters, so multi-byte (CJK, emoji) names hit it sooner.

Source

Thrown at api/db/services/document_service.py:127

        docs = docs.paginate(page_number, items_per_page)

        docs_list = list(docs.dicts())
        doc_ids_on_page = [doc["id"] for doc in docs_list]
        metadata_map = DocMetadataService.get_metadata_for_documents(doc_ids_on_page, kb_id) if doc_ids_on_page else {}
        for doc in docs_list:
            doc["meta_fields"] = metadata_map.get(doc["id"], {})
        return docs_list, count

    @classmethod
    @DB.connection_context()
    def check_doc_health(cls, tenant_id: str, filename):
        import os

        MAX_FILE_NUM_PER_USER = int(os.environ.get("MAX_FILE_NUM_PER_USER", 0))
        if 0 < MAX_FILE_NUM_PER_USER <= DocumentService.get_doc_count(tenant_id):
            raise RuntimeError("Exceed the maximum file number of a free user!")
        if len(filename.encode("utf-8")) > FILE_NAME_LEN_LIMIT:
            raise RuntimeError("Exceed the maximum length of file name!")
        return True

    @classmethod
    @DB.connection_context()
    def get_by_kb_id(cls, kb_id, page_number, items_per_page, orderby, desc, keywords, run_status, types, suffix, name=None, doc_ids=None, return_empty_metadata=False):
        fields = cls.get_cls_model_fields()
        if keywords:
            docs = (
                cls.model.select(*[*fields, UserCanvas.title.alias("pipeline_name"), User.nickname])
                .join(File2Document, on=(File2Document.document_id == cls.model.id))
                .join(File, on=(File.id == File2Document.file_id))
                .join(UserCanvas, on=(cls.model.pipeline_id == UserCanvas.id), join_type=JOIN.LEFT_OUTER)
                .join(User, on=(cls.model.created_by == User.id), join_type=JOIN.LEFT_OUTER)
                .where((cls.model.kb_id == kb_id), (fn.LOWER(cls.model.name).contains(keywords.lower())))
            )
        else:
            docs = (
                cls.model.select(*[*fields, UserCanvas.title.alias("pipeline_name"), User.nickname])

View on GitHub (pinned to 554fb1133a)

Solutions

1. Shorten the filename before upload (strip extension redundancy, truncate title).
2. Keep names within the limit accounting for multi-byte characters (assume ~3 bytes/CJK char).
3. Pre-check byte length client-side: new TextEncoder().encode(name).length.

Example fix

// before
const name = paper.title + " - full abstract...";
// after
const enc = new TextEncoder();
const name = enc.encode(paper.title).length > 255 ? paper.title.slice(0, 80) : paper.title;

from api.settings import FILE_NAME_LEN_LIMIT  # or the constant's module

if len(filename.encode('utf-8')) > FILE_NAME_LEN_LIMIT:
    filename = filename.encode('utf-8')[:FILE_NAME_LEN_LIMIT].decode('utf-8', 'ignore')

try:
    DocumentService.check_doc_health(tenant_id, filename)
except RuntimeError as e:
    if 'maximum length of file name' in str(e):
        filename = truncate_utf8(filename, FILE_NAME_LEN_LIMIT); retry
    else:
        raise

When it happens

Trigger: Uploading/creating a document whose filename encoded as UTF-8 is longer than the DB column's FILE_NAME_LEN_LIMIT bytes.

Common situations: Verbose auto-generated names (exports, papers with full titles); CJK filenames where each character costs 3 bytes; concatenating metadata into the filename client-side.

Related errors

• Space name is required
• This type of file has not been supported yet!
• main() must be defined or exported.
• main() must return a value. Use null for an empty result.
• main() returned a non-JSON-serializable value.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/370ab0af2e855fc9. Report an issue: GitHub.