datawhalechina/hello-agents · error · FileNotFoundError

未找到 {env_path} 请执行: copy .env.example backend\.env 并填入 TMDB

Error message

未找到 {env_path}
请执行: copy .env.example backend\.env  并填入 TMDB / LLM 密钥

What it means

FileNotFoundError raised by the beep-YingQian notebook's setup cell when backend/.env does not exist relative to the notebook's working directory. The cell deliberately fails fast instead of proceeding with missing TMDB/LLM keys, because downstream cells call TMDB and LLM APIs that would fail anyway. The message embeds both the expected absolute path and the Windows-style copy command from the template.

Source

Thrown at Co-creation-projects/aatanxiao12-beep-YingQian/main.ipynb:53

      "outputs": [],
      "source": [
        "import os\n",
        "import sys\n",
        "from pathlib import Path\n",
        "\n",
        "# 项目根目录 = 本 notebook 所在目录\n",
        "ROOT = Path.cwd().resolve()\n",
        "BACKEND = ROOT / \"backend\"\n",
        "assert (BACKEND / \"app\").exists(), f\"找不到 backend/app，请在项目根目录打开 notebook（当前: {ROOT}\"\n",
        "\n",
        "sys.path.insert(0, str(BACKEND))\n",
        "\n",
        "# 优先加载 backend/.env\n",
        "from dotenv import load_dotenv\n",
        "\n",
        "env_path = BACKEND / \".env\"\n",
        "if not env_path.exists():\n",
        "    raise FileNotFoundError(\n",
        "        f\"未找到 {env_path}\\n\"\n",
        "        \"请执行: copy .env.example backend\\\\.env  并填入 TMDB / LLM 密钥\"\n",
        "    )\n",
        "load_dotenv(env_path)\n",
        "\n",
        "print(\"ROOT   :\", ROOT)\n",
        "print(\"BACKEND:\", BACKEND)\n",
        "print(\"TMDB   :\", \"已配置\" if (os.getenv(\"TMDB_ACCESS_TOKEN\") or os.getenv(\"TMDB_API_KEY\")) else \"缺失\")\n",
        "print(\"LLM    :\", \"已配置\" if os.getenv(\"LLM_API_KEY\") else \"缺失\")\n",
        "print(\"MODEL  :\", os.getenv(\"LLM_MODEL_ID\") or \"(未设置)\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "\n",

View on GitHub (pinned to 606a07d341)

Solutions

1. Create the file at the exact path shown in the error message: <project root>/backend/.env, copying from .env.example, then fill TMDB_ACCESS_TOKEN (or TMDB_API_KEY) and LLM_API_KEY.
2. Ensure the notebook kernel's cwd is the project root — the assert on backend/app existing usually catches this first; restart Jupyter from the project directory if needed.
3. On Windows, verify the file is really named .env (dir /a, enable 'show file extensions'); rename .env.txt to .env.
4. Re-run the setup cell and confirm the printed TMDB/LLM lines show 已配置 before running later cells.

Example fix

// before
env_path = BACKEND / ".env"
if not env_path.exists():
    raise FileNotFoundError(
        f"未找到 {env_path}\n"
        "请执行: copy .env.example backend\\.env  并填入 TMDB / LLM 密钥"
    )

// after (also accept root .env, cross-platform hint)
env_path = next((p for p in (BACKEND / ".env", ROOT / ".env") if p.exists()), None)
if env_path is None:
    raise FileNotFoundError(
        f"未找到 {BACKEND / '.env'} 或 {ROOT / '.env'}\n"
        "请执行: cp .env.example backend/.env (Windows: copy .env.example backend\\.env) 并填入 TMDB / LLM 密钥"
    )

from pathlib import Path

def env_is_ready(backend: Path) -> tuple[bool, str]:
    env_path = backend / ".env"
    if not env_path.exists():
        return False, f"missing {env_path}"
    keys = env_path.read_text()
    missing = [k for k in ("TMDB_ACCESS_TOKEN", "LLM_API_KEY") if f"{k}=" not in keys]
    if missing:
        return False, f"keys not set: {missing}"
    return True, "ok"

# before running the notebook pipeline:
ok, why = env_is_ready(Path.cwd() / "backend")
if not ok:
    raise SystemExit(f"环境未就绪: {why}")

try:
    load_dotenv(env_path)
except FileNotFoundError as e:
    print(f"{e} — 请先创建 backend/.env（可从 .env.example 复制）")
    raise

When it happens

Trigger: Running the first code cell when Path.cwd()/backend/.env is absent: fresh clone where only .env.example exists; notebook launched from a directory other than the project root (BACKEND is derived from Path.cwd(), so starting Jupyter from the repo root or a parent makes BACKEND point at a nonexistent path); .env created but in the project root instead of backend/; file saved as .env.txt by Windows editors that append extensions.

Common situations: Windows users running 'copy .env.example backend\.env' in the wrong directory; file explorer hiding extensions creating .env.txt; starting VS Code/Jupyter from the repo root so cwd differs from the notebook's folder; forgetting to duplicate the template after pull on a new machine.

Related errors

• Missing required environment variables: {missing_env_vars}.
• 请设置 LLM_API_KEY 环境变量
• 缺少 LLM 配置：{missing}。请先复制并填写 .env。
• AI 服务未配置，请设置 OPENAI_API_KEY
• 向量生成器初始化失败: {str(e)}

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/9248768552502088. Report an issue: GitHub.