> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 常见问题、错误信息与排查路径

建议按“解析 → 分派 → 数据 → 并发”分层排查。

先用错误类型快速定位，再补齐现场信息（target/参数/变量/线程）以缩小范围。

## 快速定位

下面列出各阶段的典型错误与立即检查项：

* **解析**：`MultipleParseException`
  * 立即检查：`ex.formatDiagnostic()` 打印源码摘录
  * REPL：语句前加 `$` 输出 AST
* **分派**：`FunctionNotFoundError` / `EvaluatorNotFoundError`
  * 立即检查：`Environment#getRootFunctions()` / `getRootExtensionFunctions()`
  * 命名空间与 target 类型是否匹配
* **数据**：`ArgumentTypeMismatchError` / `VariableNotFoundError` / `IndexAccessError` / `VoidError`
  * 立即检查：`FunctionContext#toString()`（函数名/target/参数）
  * 参考：`availableVariables`、`IndexErrorType`
* **并发**：主线程函数跑在后台 / 异步任务堆积
  * 立即检查：`registerPrimarySyncFunction` 用法
  * 观察：`ThreadPoolManager#getActiveTaskCount()` 与执行器配置

## 解析错误（MultipleParseException）

* `Parser#parse` 聚合所有语法错误；`ex.formatDiagnostic()` 可直接打印行列与源码摘录。
* REPL 语句前加 `$`，控制台会输出词法/语法树，便于确认括号、`then/else` 是否成对。
* 网络/数据库来源的脚本注意行尾统一，否则列号可能偏移。

## 调用分派问题

### FunctionNotFoundError

* 注册是否生效：`Environment#getRootFunctions()` / `getRootExtensionFunctions()` 查看。
  缺失则重新注册并调用 `runtime.newEnvironment()` 触发 bake。
* 命名空间：`registerFunction("fs", "readText", …)` 对应脚本 `fs:readText`，漏前缀会直接失败。
* target 类型：扩展函数要求 `target` 与注册类型一致；`null::fn()` 会因 target 为空而匹配不到。
* 目录一致性：必要时重跑 `./gradlew :core:dumpFluxonCatalog`，确认导出的签名与预期一致。

### EvaluatorNotFoundError

* 新增语法未提供求值器导致。
* 检查是否在 `runtime.function` / `index` 注册 evaluator。
* 如果语法应被禁止，在解析阶段直接抛 `ParseException`，避免运行时才失败。

## 数据与类型问题

### ArgumentTypeMismatchError

* `FunctionContext#getInt/getAsDouble` 等方法会在消息中标注参数索引与实际值；先核实脚本入参是否符合签名。
* 多参数版本只检查参数个数，不会自动装箱；需要在实现内区分 `Number`/`String` 等类型。
* 扩展函数建议先用 `getArgumentCount()` 判断参数个数，避免索引越界。

### VariableNotFoundError

* `:vars`（REPL）或 `Environment#getRootVariables()` 查看当前可见变量；确认作用域与命名是否一致。
* 函数体中新增局部变量时，确保解析器同步更新 `localVariableNames`，否则赋值索引会错位。

### IndexAccessError

* `OUT_OF_BOUNDS`：检查索引与集合大小。
* `UNSUPPORTED_TYPE` / `UNSUPPORTED_SET_TYPE`：该类型未实现 `IndexAccessor`，需要添加实现或更换访问方式。
* `NULL_TARGET`：目标为 `null`；脚本侧加判空或默认值（Elvis）再访问。

### VoidError

函数返回 `Function.VOID` 却继续参与运算时触发。仅在确实无需返回值的路径返回 `VOID`，其他场景返回真实结果或 `null`。

## 并发与执行器

* 主线程函数：仅通过 `registerPrimarySyncFunction` / `registerSyncExtensionFunction` 标记。
* 执行器：使用 `FluxonRuntime#setPrimaryThreadExecutor` 指向宿主主线程。
* 异步任务：`ThreadPoolManager#getActiveTaskCount()` 观察堆积。
* 若出现 `CallerRunsPolicy`，表示队列满，新任务会落到调用线程；需要拆批或扩容。
* 关闭：`ThreadPoolManager#shutdown()` 前最好等待 `awaitTermination`，避免异步任务被硬中断。

## 现场信息速查

* `Environment#getRootFunctions()/getRootExtensionFunctions()/getRootVariables()`：注册表与可见符号。
* `FunctionContext#toString()`：函数名、target、参数实参。
* `FluxonRuntime#getSystemFunctions()` / `#getExtensionFunctions()`：宿主侧直接查看注册状态。
* `./gradlew :core:dumpFluxonCatalog` + `vscode-extension/scripts/sync-catalog.js`：当补全或文档与运行时不一致时优先刷新。

按上述顺序（定位异常 → 获取现场 → 修正注册/类型/线程配置）即可快速收敛问题，减少反复试错。

## 相关链接

* [命令行与 REPL](/guides/cli)
* [解释器执行流](/runtime/interpreter)
* [环境与作用域](/runtime/environment)
* [运行时配置与调试](/developer/runtime-config)
* [术语表](/appendix/glossary)