{"record":{"id":"370ab0af2e855fc9","repo":"infiniflow/ragflow","slug":"exceed-the-maximum-length-of-file-name","errorCode":null,"errorMessage":"Exceed the maximum length of file name!","messagePattern":"Exceed the maximum length of file name!","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"api/db/services/document_service.py","lineNumber":127,"sourceCode":"        docs = docs.paginate(page_number, items_per_page)\n\n        docs_list = list(docs.dicts())\n        doc_ids_on_page = [doc[\"id\"] for doc in docs_list]\n        metadata_map = DocMetadataService.get_metadata_for_documents(doc_ids_on_page, kb_id) if doc_ids_on_page else {}\n        for doc in docs_list:\n            doc[\"meta_fields\"] = metadata_map.get(doc[\"id\"], {})\n        return docs_list, count\n\n    @classmethod\n    @DB.connection_context()\n    def check_doc_health(cls, tenant_id: str, filename):\n        import os\n\n        MAX_FILE_NUM_PER_USER = int(os.environ.get(\"MAX_FILE_NUM_PER_USER\", 0))\n        if 0 < MAX_FILE_NUM_PER_USER <= DocumentService.get_doc_count(tenant_id):\n            raise RuntimeError(\"Exceed the maximum file number of a free user!\")\n        if len(filename.encode(\"utf-8\")) > FILE_NAME_LEN_LIMIT:\n            raise RuntimeError(\"Exceed the maximum length of file name!\")\n        return True\n\n    @classmethod\n    @DB.connection_context()\n    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):\n        fields = cls.get_cls_model_fields()\n        if keywords:\n            docs = (\n                cls.model.select(*[*fields, UserCanvas.title.alias(\"pipeline_name\"), User.nickname])\n                .join(File2Document, on=(File2Document.document_id == cls.model.id))\n                .join(File, on=(File.id == File2Document.file_id))\n                .join(UserCanvas, on=(cls.model.pipeline_id == UserCanvas.id), join_type=JOIN.LEFT_OUTER)\n                .join(User, on=(cls.model.created_by == User.id), join_type=JOIN.LEFT_OUTER)\n                .where((cls.model.kb_id == kb_id), (fn.LOWER(cls.model.name).contains(keywords.lower())))\n            )\n        else:\n            docs = (\n                cls.model.select(*[*fields, UserCanvas.title.alias(\"pipeline_name\"), User.nickname])","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/api/db/services/document_service.py#L109-L145","documentation":"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.","triggerScenarios":"Uploading/creating a document whose filename encoded as UTF-8 is longer than the DB column's FILE_NAME_LEN_LIMIT bytes.","commonSituations":"Verbose auto-generated names (exports, papers with full titles); CJK filenames where each character costs 3 bytes; concatenating metadata into the filename client-side.","solutions":["Shorten the filename before upload (strip extension redundancy, truncate title).","Keep names within the limit accounting for multi-byte characters (assume ~3 bytes/CJK char).","Pre-check byte length client-side: new TextEncoder().encode(name).length."],"exampleFix":"// before\nconst name = paper.title + \" - full abstract...\";\n// after\nconst enc = new TextEncoder();\nconst name = enc.encode(paper.title).length > 255 ? paper.title.slice(0, 80) : paper.title;","handlingStrategy":"validation","validationCode":"from api.settings import FILE_NAME_LEN_LIMIT  # or the constant's module\n\nif len(filename.encode('utf-8')) > FILE_NAME_LEN_LIMIT:\n    filename = filename.encode('utf-8')[:FILE_NAME_LEN_LIMIT].decode('utf-8', 'ignore')","typeGuard":null,"tryCatchPattern":"try:\n    DocumentService.check_doc_health(tenant_id, filename)\nexcept RuntimeError as e:\n    if 'maximum length of file name' in str(e):\n        filename = truncate_utf8(filename, FILE_NAME_LEN_LIMIT); retry\n    else:\n        raise","preventionTips":["Measure byte length, not character count, for CJK filenames.","Strip long metadata suffixes from generated filenames before upload."],"tags":["validation","filename","upload","length-limit"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}