langgenius/dify · error · ArchivedDocumentImmutableError

archived_document_immutable

archived_document_immutable

Error message

The archived document is not editable.

What it means

HTTP 403, error_code archived_document_immutable, raised by DocumentPauseApi.patch when DocumentService.check_archived(document) returns True (datasets_document.py:1409). Archived documents are frozen and cannot be paused, resumed, or edited until un-archived.

Source

Thrown at api/controllers/console/datasets/datasets_document.py:1410

    def patch(
        self,
        session: Session,
        current_tenant_id: str,
        current_user: Account,
        dataset_id: UUID,
        document_id: UUID,
    ):
        """pause document."""
        dataset_id_str = str(dataset_id)
        document_id_str = str(document_id)

        document = self.get_document(session, dataset_id_str, document_id_str, current_user, current_tenant_id)
        if not current_user.is_dataset_editor:
            raise Forbidden()

        # 403 if document is archived
        if DocumentService.check_archived(document):
            raise ArchivedDocumentImmutableError()

        check_knowledge_rate_limit()
        try:
            # pause document
            DocumentService.pause_document(document, session)
        except services.errors.document.DocumentIndexingError:
            raise DocumentIndexingError("Cannot pause completed document.")

        return "", 204


@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/resume")
class DocumentRecoverApi(DocumentResource):
    @setup_required
    @login_required
    @account_initialization_required
    @console_ns.response(204, "Document resumed successfully")
    @with_current_user

View on GitHub (pinned to ef8544b173)

Solutions

1. Un-archive the document first via PATCH .../documents/status/un_archive/batch if processing is required.
2. Otherwise no action is needed - archived documents are intentionally immutable.
3. Hide pause/resume controls for archived documents in the UI.

doc = console.get_document(dataset_id, document_id)
if doc.get("archived"):
    raise RuntimeError("Cannot pause an archived document; un-archive it first.")

def is_archived(doc: dict) -> bool:
    return bool(doc.get("archived"))

try:
    console.pause_document(dataset_id, document_id)
except HTTPError as e:
    if e.response.status_code == 403 and e.response.json().get("code") == "archived_document_immutable":
        notify_user("This document is archived. Un-archive it before pausing.")
    else:
        raise

When it happens

Trigger: PATCH .../documents/{id}/processing/pause on a document whose archived flag is True (it was previously archived via the batch archive action).

Common situations: User selects an archived document and the pause control is still shown; bulk archive followed by an attempt to pause an item in the selection.

Related errors

• You don't have the permission to access the requested resour
• access_denied
• server_5xx
• Knowledge creation failed during create
• Knowledge creation failed during policy

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