500错误是服务器端未捕获的致命故障，需优先清浏览器缓存并刷新；若无效，则检查.env配置、查看实时日志定位报错行、验证数据库连接与表结构、排查沙箱超时或权限问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在使用 Fitten Code 提交代码或触发后端处理时，页面突然弹出“500：服务器内部错误”，说明请求已抵达服务端但被异常中断——这不是你本地网络或浏览器的问题，而是后端在执行过程中遇到了未捕获的致命故障。
先确认是不是你这边能快速解决的
这一步操作起来很简单，直接把文件拖进去就行。打开浏览器，按 Ctrl+Shift+Delete（Windows/Linux）或 Cmd+Shift+Delete（macOS），勾选“缓存的图像和文件”“Cookie及其他网站数据”，点击“清除数据”。刷新页面重试一次。
如果清除后仍报500，说明问题不在客户端缓存层，【必须转向服务端排查】，继续往下看。
检查 .env 或配置文件是否被意外修改
Fitten Code 依赖环境变量加载数据库地址、密钥、API端点等关键参数。若 .env 文件中某一行末尾多了空格、漏了引号、写错大小写（如 DATABASE_URL 写成 database_url），Node.js 或 Python 后端启动时不会报错，但首次请求就会崩出500。
打开项目根目录下的 .env 文件，逐行核对：
- 所有值必须用双引号包裹（如
API_KEY="sk-xxx"） - 不能有中文字符、全角符号、BOM头
- 【DATABASE_URL 必须是完整可连接的字符串，且端口与实际 PostgreSQL/MySQL 实例一致】
改完保存，重启后端进程（如 npm run dev 或 uvicorn main:app --reload）。
查看实时日志定位具体错误行
方法一：本地开发环境
终端里运行后端服务时，错误堆栈会直接打印在控制台。重点找以 Traceback (most recent call last):（Python）或 at Object.<anonymous></anonymous>（Node.js）开头的段落，最后一行通常是真实报错位置，比如 File "app/routers/code.py", line 47, in execute_code。
方法二：生产环境（Docker / PM2 / systemd）
执行：docker logs fitten-backend --tail 50 -f（容器名按实际替换）；或 pm2 logs fitten-code；或 journalctl -u fitten-code.service -n 50 -f。滚动到最新报错处，看是否有 TypeError: Cannot read property 'length' of null 这类明确指向某变量未定义的提示。
注意：日志里出现 psycopg2.OperationalError 或 ConnectionRefusedError，说明数据库根本没连上——不是SQL写错，是服务压根没启动或网络不通。
Fitten Code 1.0.3是一款由清华博士团队打造的AI编程助手，基于国产计图（Jittor）深度学习框架开发。它支持VS Code、JetBrains系列等主流IDE及80多种编程语言。核心功能包括智能代码补全、注释生成、代码解释、Bug检测、单元测试生成等，旨在全方位提升开发效率。该工具对个人用户免费开放。
验证数据库连接与表结构一致性
第一步：用命令行直连数据库
psql -h localhost -U fitten_user -d fitten_db（PostgreSQL）或 mysql -h 127.0.0.1 -u fitten_user -p fitten_db（MySQL），输入密码后进入交互界面。
第二步：检查关键表是否存在且字段匹配
运行 \dt（PostgreSQL）或 SHOW TABLES;（MySQL），确认 submissions、users 等表在列；再用 SELECT * FROM submissions LIMIT 1; 看能否返回结果。如果报 relation "submissions" does not exist，说明迁移脚本没跑或失败了。
第三步：执行迁移（仅当确认缺失表时）
回到项目目录，运行 alembic upgrade head（SQLAlchemy）或 prisma migrate deploy（Prisma）。【切勿跳过迁移前的备份步骤，线上环境必须先 dump 数据】
等待机制失效的典型表现与修复
Fitten Code 在执行用户提交的代码时，会启动沙箱进程并设置超时（默认 8 秒）。但以下情况会导致等待逻辑崩溃，返回500而非超时提示：
① 沙箱进程因权限被 kill：宿主机 SELinux 或 AppArmor 阻止了 unshare 系统调用，导致容器无法隔离；
② 超时信号未被正确捕获：Python 的 signal.alarm() 在多线程下失效，Node.js 的 child_process.kill('SIGTERM') 被忽略；
③ 沙箱 stdout/stderr 缓冲区溢出：用户代码疯狂打印日志（如 while True: print("a"*1000)），填满 4MB 缓冲区后阻塞，主进程卡死。
临时绕过方式：在 backend/sandbox/runner.py 中将 timeout=8 改为 timeout=15，并添加 stderr=subprocess.PIPE, stdout=subprocess.PIPE, bufsize=1 强制行缓冲。
