Skip to main content

Troubleshooting & Limitations

Known limitations​

  • Forge works on your project's files, not a live server. Generation, validation, and "what's in my project" answers all read the JSON/C# files in your customization folder. To work against what's deployed, run Import Schema from Server first.
  • The AI agent still owns the thinking. Forge keeps the agent honest about Protrak contracts and your schema, but it can't catch a misunderstood requirement. Always review generated code and JSON before committing or deploying.
  • Validation is static, not a full build. Program validation catches common mistakes (wrong interface, bad attribute access, type mismatches). A real compile runs only if you have the .NET SDK installed and a project referencing Prorigo.Protrak.Toolkit.
  • Generation covers the elements listed under Authoring with AI. Other parts of a Protrak schema can still be imported and exported, but Forge won't scaffold them for you — author those in Protrak directly.
  • Classic layouts are read-only. Forge does not author classic Home/Create/View/Edit/Report/Dashboard layouts; use Design Studio (Forms, Type Widgets, Layout Templates) for new layout work.
  • Naming is PascalCase. Schema element names must be PascalCase.
  • The workspace audit reports; it never repairs. Checking your workspace is read-only, covers structural problems only (references, names, promote loops) — not naming conventions or business correctness — and its warnings and info findings often describe intentional design. Read them before acting on them.

"Protrak Forge server failed to start" (VS Code)​

  1. Check View → Output → Protrak Forge.
  2. Make sure the workspace contains Types/ and/or Programs/, or a .csproj referencing Prorigo.Protrak.Toolkit.
  3. If detection fails, run Protrak Forge: Set Protrak Project Root… to point Forge at the right folder.

No types or programs found​

Forge returns empty results (with a note) when those directories are missing — this isn't an error. Make sure you opened the customization folder itself, not a parent directory.

Workspace not detected​

Auto-detection looks for either a .csproj referencing Prorigo.Protrak.Toolkit or a folder with both Types/ and Programs/. If it misses:

  • VS Code: run Protrak Forge: Set Protrak Project Root….
  • Claude Code: set "cwd": "/path/to/project" in settings.local.json.
  • Codex / any client: set PROTRAK_PROJECT_ROOT to the absolute path of your customization repo.

Enable debug logging​

Set PROTRAKFORGE_LOG_LEVEL=DEBUG.

In VS Code, via .vscode/settings.json:

{ "terminal.integrated.env.osx": { "PROTRAKFORGE_LOG_LEVEL": "DEBUG" } }

(Use linux or windows in place of osx.) For Claude Code or Codex, add it to the MCP server config's env block.

Updating​

The VS Code extension updates automatically through the Marketplace and pulls a matching MCP server version via npx. To force-update the CLI manually:

npm install -g @prorigo/protrak-forge@latest