{
  "id": "llm/llamaindex-persist-dir-permission",
  "signature": "PermissionError: [Errno 13] Permission denied: '/app/data/index_store.json' — LlamaIndex cannot persist index to storage",
  "signature_zh": "PermissionError: [Errno 13] 权限被拒绝：'/app/data/index_store.json'——LlamaIndex 无法将索引持久化到存储",
  "regex": "PermissionError.*Errno 13.*LlamaIndex.*persist",
  "domain": "llm",
  "category": "system_error",
  "subcategory": null,
  "root_cause": "LlamaIndex requires write permissions to the persist directory; when running in containers or restricted environments, the application user lacks write access to the specified path.",
  "root_cause_type": "generic",
  "root_cause_zh": "LlamaIndex 需要对持久化目录的写权限；在容器或受限环境中运行时，应用程序用户对指定路径缺乏写访问权限。",
  "versions": [
    {
      "version": "llama-index>=0.10.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "llama-index-core>=0.10.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Running as root is a security risk and may not be allowed in production environments with security policies",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "/tmp is ephemeral and may be cleared on container restart or by system cleanup, losing persisted index data",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Disabling persistence means the index must be rebuilt on every restart, increasing latency and API costs",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure the persist directory exists and is writable by the application user: mkdir -p /app/data && chown -R appuser:appuser /app/data",
      "success_rate": 0.95,
      "how": "Ensure the persist directory exists and is writable by the application user: mkdir -p /app/data && chown -R appuser:appuser /app/data",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a Docker volume with proper permissions: docker run -v ./data:/app/data my-app, and set the user ID in the Dockerfile to match the host user.",
      "success_rate": 0.9,
      "how": "Use a Docker volume with proper permissions: docker run -v ./data:/app/data my-app, and set the user ID in the Dockerfile to match the host user.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Configure LlamaIndex to use a different storage backend like S3 or GCS that bypasses filesystem permissions: from llama_index.storage.storage_context import StorageContext; from llama_index.storage.docstore.s3 import S3DocumentStore",
      "success_rate": 0.85,
      "how": "Configure LlamaIndex to use a different storage backend like S3 or GCS that bypasses filesystem permissions: from llama_index.storage.storage_context import StorageContext; from llama_index.storage.docstore.s3 import S3DocumentStore",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "确保持久化目录存在且应用程序用户可写：mkdir -p /app/data && chown -R appuser:appuser /app/data",
    "使用具有适当权限的 Docker 卷：docker run -v ./data:/app/data my-app，并在 Dockerfile 中设置用户 ID 以匹配主机用户。",
    "配置 LlamaIndex 使用其他存储后端（如 S3 或 GCS）以绕过文件系统权限：from llama_index.storage.storage_context import StorageContext; from llama_index.storage.docstore.s3 import S3DocumentStore"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.llamaindex.ai/en/stable/module_guides/storing/persistence.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2024-01-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}