langgenius/dify · error · NotFound

not_found

not_found

Error message

Document not found.

What it means

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.

Source

Thrown at api/controllers/console/datasets/datasets_segments.py:175

    console_ns,
    SegmentResponse,
    ConsoleSegmentListResponse,
    SegmentDetailResponse,
    ChildChunkDetailResponse,
    ChildChunkListResponse,
    ChildChunkBatchUpdateResponse,
    SegmentBatchImportStatusResponse,
    SimpleResultResponse,
)


def _get_segment_for_document(
    session: Session, dataset: Dataset, document: Document, segment_id: str
) -> tuple[SegmentRef, DocumentSegment]:
    dataset_ref = DatasetRefService.create_dataset_ref(dataset)
    document_ref = DatasetRefService.create_document_ref(dataset_ref, document)
    if document_ref is None:
        raise NotFound("Document not found.")

    segment_ref = DatasetRefService.create_segment_ref(document_ref, segment_id)
    segment = SegmentService.get_segment_by_ref(segment_ref, session=session)
    if not segment:
        raise NotFound("Segment not found.")
    return segment_ref, segment


@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments")
class DatasetDocumentSegmentListApi(Resource):
    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
    @console_ns.doc(params=query_params_from_model(SegmentListQuery))
    @console_ns.response(200, "Segments retrieved successfully", console_ns.models[ConsoleSegmentListResponse.__name__])
    @setup_required
    @login_required
    @account_initialization_required
    @with_current_user
    @with_current_tenant_id

View on GitHub (pinned to ef8544b173)

Solutions

1. Confirm the document exists under the dataset via GET /datasets/{dataset_id}/documents/{document_id} before the segment call.
2. Re-fetch the document list for the dataset and use a verified ID.
3. Handle 404 by invalidating the client's cached document reference.

Example fix

# before
client.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')

# after
if client.get(f'/datasets/{dataset_id}/documents/{document_id}').status_code == 404:
    raise LookupError('document not in this dataset')
client.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')

if client.get(f'/console/api/datasets/{dataset_id}/documents/{document_id}').status_code != 200:
    raise LookupError(f'document {document_id} not in dataset {dataset_id}')

def document_in_dataset(resp: requests.Response) -> bool:
    return resp.status_code == 200

try:
    client.get(f'/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}')
except HTTPError as e:
    if e.response.status_code == 404 and 'Document' in e.response.text:
        # refresh document list; discard stale id
        ...

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• not_found
• Data source binding not found.
• Credential not found.
• Dataset not found.
• File not found.

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