故障排查GitHub issue3 分钟阅读排错/错误码

解决FastGPT启动时PostgreSQL连接参数解析失败的问题

执行pnpm dev启动FastGPT项目时,控制台会打印Next.js启动信息,包括Environments: .env.local,随后打印MongoDB连接成功的日志,加载systemConfigs、appplugingroups等多个数据库表的信息,但在启动过程中会出现PostgreSQL连接报错。

现象

执行pnpm dev启动FastGPT项目时,控制台会打印Next.js启动信息,包括Environments: .env.local,随后打印MongoDB连接成功的日志,加载systemConfigs、appplugingroups等多个数据库表的信息,但在启动过程中会出现PostgreSQL连接报错。具体报错信息为[Error] 2025-08-29 15:23:21 pg connect error,详细错误内容为Cannot read properties of undefined (reading 'searchParams'),错误堆栈指向pg-connection-string模块的parse函数。

可能原因

该报错源于PostgreSQL连接字符串解析失败。根据错误堆栈,pg-connection-string模块尝试读取undefined对象的searchParams属性,说明项目配置的PostgreSQL连接参数存在格式错误,或关键配置项缺失、未正确加载。

排查步骤

  1. 检查项目的.env.local文件中的PostgreSQL相关配置,确认配置内容是否完整且符合标准格式。
  2. 核对PostgreSQL连接字符串的标准写法,确保包含必要的连接信息,如数据库地址、端口、用户名、密码和目标数据库名称。
  3. 确认启动进程是否正确加载了.env.local文件中的环境变量,避免配置未生效的情况。
  4. 检查连接字符串中是否存在未转义的特殊字符,导致解析异常。

解决与验证

解决该问题需要修正PostgreSQL连接配置:确保连接字符串格式符合标准,例如使用postgresql://username:password@host:port/database的格式,或正确拆分配置为独立的环境变量参数。修正配置后,重新执行pnpm dev启动项目,验证是否不再出现pg connect error报错,且服务能正常启动到http://localhost:3000

来源:FastGPT GitHub issue