troubleshoot git:20261101.37abc00A

Immutable. This exact content never changes and is served at /api/v1/blob/befd43d29a580e7b.

---
name: troubleshoot
description: Fix ReversePort errors and odd results — unreadable scenes, packs that will not list, missing dependencies in the graph, refused output folders, unsafe paths, big files, a repeated failing call, a damaged plan, the engine missing or stopping, MCP connection and protocol errors. Use when a ReversePort tool returns an error or a result looks wrong.
---

# Troubleshooting ReversePort

| Error / symptom                                    | Cause                                                                    | Fix                                                                                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `NOT_FOUND`, `NOT_A_FILE`, `NOT_A_FOLDER`          | Wrong path or kind                                                       | Absolute paths are safest; `re_scan` wants a folder, `re_binary`/`re_archive`/`re_probe` a file.                                |
| `BAD_FORMAT` on a Unity scene                      | Binary serialization                                                     | Unity: Project Settings → Editor → Asset Serialization = Force Text, then save.                                                 |
| `UNSUPPORTED_SCENE` on .scn/.res                   | Godot binary resource                                                    | Open in Godot, Save As .tscn/.tres.                                                                                             |
| `NOT_A_PCK`                                        | No GDPC header, trailer or `pck` section                                 | The pack may be next to the executable (`*.pck`), or the build is not Godot (`re_scan` the folder).                             |
| `encryptedDirectory: true`                         | Encrypted Godot export                                                   | Not supported by design. Use the project source.                                                                                |
| `UNSUPPORTED_ARCHIVE` (Unity bundle, Unreal pak)   | Identified only                                                          | Port from the project source instead.                                                                                           |
| Graph misses an edge                               | Dynamic loads (`load(path_var)`, reflection, string-built paths)         | Read the code; add the dependency to your notes. Type references need class names of 3+ characters.                             |
| `OUTPUT_NOT_EMPTY`                                 | The output folder has files ReversePort did not create                   | Choose a new folder; ReversePort never overwrites foreign files.                                                                |
| `UNSAFE_PATH`                                      | A path tried to leave the output/extraction folder                       | Use paths relative to the output project, without `..`.                                                                         |
| `INVALID_ARGUMENT … Unknown argument`              | Typo in an argument name                                                 | The message lists the allowed names.                                                                                            |
| Large results truncated                            | Limits keep answers readable                                             | Use `match`, `limit`, `offset`, or point at a subfolder. `outputTruncated.fullOutputUri` reads the whole result (MCP resource). |
| `UNKNOWN_TOOL`                                     | A name that is not in this server                                        | Use the name the message suggests, or one from `tools/list`. Tools left out of a compact list still work by name.               |
| `error.repeated` (same call failed 2+ times)       | The same call with the same arguments keeps failing                      | Do not send it again unchanged: change the input, use another tool, or tell the user what blocks.                               |
| `UNKNOWN_PLAN` / `PLAN_UNREADABLE` / `recovered`   | Wrong planId / damaged plan file / continued from its backup             | `port_status {}` lists plans. After `recovered`, check `port_status {planId}` for the last step before going on.                |
| `ENGINE_UNAVAILABLE`                               | The deep-analysis engine is not built or not installed                   | Continue with ReversePort's own tools; ask the user before installing (see the next rows).                                      |
| `ENGINE_STOPPED`                                   | The engine process exited during a call                                  | Call the engine tool once more: it restarts. ReversePort's own tools keep working.                                              |
| `ENGINE_RESTART_LIMIT`                             | The engine stopped three times in a row                                  | Tell the user, suggest `reverseport doctor` and a client restart; continue with ReversePort's own tools.                        |
| JSON-RPC `-32022` / `-32021` / `-32001`            | Unsupported MCP version / tasks without the extension / old HTTP session | `-32022` lists the supported versions; `-32021` names the missing capability; `-32001`: send `initialize` again.                |
| MCP server not visible                             | Client not restarted / Node too old / not registered                     | `reverseport doctor` (it names the Node version it needs), `reverseport setup`, then restart the agent app.                     |
| Only `re_*`/`port_*` tools are listed              | The deep-analysis engine is not built                                    | From npm: `npx -y reverseport@latest setup`. Git checkout: `npm ci && npm run build`, then restart the agent.                   |
| Only ReversePort tools listed (Claude Code plugin) | The plugin does not include the engine                                   | Ask the user to turn on the plugin's Deep-analysis engine setting (`/plugin` → reverseport → configure); do not also run setup. |
| Decompile/xref tools report a missing provider     | Ghidra, Hopper or IDA not configured                                     | `reverseport doctor`, then follow docs/installation.md (provider setup).                                                        |

Workspace: `~/.reverseport` (plans in `ports/`, extracted files in `extracted/`, reports in `reports/`); set
`REVERSEPORT_HOME` to move it.