{"record":{"id":"6c735cf762d3557f","repo":"langgenius/dify","slug":"not-found-6c735c","errorCode":"not_found","errorMessage":"Document not found.","messagePattern":"Document not found\\.","errorType":"http","errorClass":"NotFound","httpStatus":404,"severity":"error","filePath":"api/controllers/console/datasets/datasets_segments.py","lineNumber":175,"sourceCode":"    console_ns,\n    SegmentResponse,\n    ConsoleSegmentListResponse,\n    SegmentDetailResponse,\n    ChildChunkDetailResponse,\n    ChildChunkListResponse,\n    ChildChunkBatchUpdateResponse,\n    SegmentBatchImportStatusResponse,\n    SimpleResultResponse,\n)\n\n\ndef _get_segment_for_document(\n    session: Session, dataset: Dataset, document: Document, segment_id: str\n) -> tuple[SegmentRef, DocumentSegment]:\n    dataset_ref = DatasetRefService.create_dataset_ref(dataset)\n    document_ref = DatasetRefService.create_document_ref(dataset_ref, document)\n    if document_ref is None:\n        raise NotFound(\"Document not found.\")\n\n    segment_ref = DatasetRefService.create_segment_ref(document_ref, segment_id)\n    segment = SegmentService.get_segment_by_ref(segment_ref, session=session)\n    if not segment:\n        raise NotFound(\"Segment not found.\")\n    return segment_ref, segment\n\n\n@console_ns.route(\"/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments\")\nclass DatasetDocumentSegmentListApi(Resource):\n    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)\n    @console_ns.doc(params=query_params_from_model(SegmentListQuery))\n    @console_ns.response(200, \"Segments retrieved successfully\", console_ns.models[ConsoleSegmentListResponse.__name__])\n    @setup_required\n    @login_required\n    @account_initialization_required\n    @with_current_user\n    @with_current_tenant_id","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/controllers/console/datasets/datasets_segments.py#L157-L193","documentation":"NotFound ('Document not found.') raised at datasets_segments.py:175 inside _get_segment_for_document when DatasetRefService.create_document_ref returns None. This means the document_id does not resolve under the given dataset, so no segment lookup is attempted. The helper centralizes dataset+document+segment resolution for several segment endpoints.","triggerScenarios":"Any segment-scoped endpoint (child-chunks, segment fetch/update) that delegates to _get_segment_for_document with a document_id that is absent, deleted, or belongs to a different dataset than the path's dataset_id.","commonSituations":"Document was deleted between listing and the segment call; document_id copied from another dataset; parent document failed to index and was soft-deleted; UUID case/typo.","solutions":["Confirm the document exists under the dataset via GET /datasets/{dataset_id}/documents/{document_id} before the segment call.","Re-fetch the document list for the dataset and use a verified ID.","Handle 404 by invalidating the client's cached document reference."],"exampleFix":"# before\nclient.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')\n\n# after\nif client.get(f'/datasets/{dataset_id}/documents/{document_id}').status_code == 404:\n    raise LookupError('document not in this dataset')\nclient.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')","handlingStrategy":"validation","validationCode":"if client.get(f'/console/api/datasets/{dataset_id}/documents/{document_id}').status_code != 200:\n    raise LookupError(f'document {document_id} not in dataset {dataset_id}')","typeGuard":"def document_in_dataset(resp: requests.Response) -> bool:\n    return resp.status_code == 200","tryCatchPattern":"try:\n    client.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')\nexcept HTTPError as e:\n    if e.response.status_code == 404 and 'Document' in e.response.text:\n        # refresh document list; discard stale id\n        ...","preventionTips":["Resolve the document through the dataset's document list, not via pasted IDs.","Invalidate cached document references after deletes/re-indexes.","Verify the dataset+document pair before any segment-scoped call."],"tags":["datasets","segments","not-found","document-ownership"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}