Skip to main content

Troubleshooting

Use this page to quickly diagnose and fix common issues. If you’re new, start with the Quick fixes. For specific errors, jump to Common issues or Error messages.

TL;DR — Quick fixes
  • Ensure prerequisites are installed (correct .NET SDK, IDE version, required workloads).
  • Run SetupServerSession first in every new workspace.
  • Verify paths: workspace, .sln, and .csproj are correct and accessible.

Before you begin​

RequirementRecommended
OSWindows/macOS/Linux (64-bit)
IDEVS Code (latest) / Visual Studio (latest)
.NET SDK9.0

Common issues​

NuGet package restore fails

Symptoms

  • When the IDE restores NuGet packages, the operation fails.
Nuget package error

Likely causes

  • You’re targeting platforms not supported by Grial: macOS, Windows, Linux, or Tizen.

Fix

  • Target only Android and iOS frameworks in your .NET MAUI app.

Verify

  • NuGet packages restore successfully.
Copilot chat messages disappear after sending

Symptoms

  • After you send a message to the AI agent and it starts answering, the message disappears.

Likely causes

  • A VS Code issue where, when the permission prompt for an MCP tool appears, chat messages briefly disappear.

Fix

  • Resize the GitHub Copilot chat panel (drag the edge) to force a refresh.

Verify

  • The MCP tool permission request is visible and you can allow or deny it.
Logs don’t appear in the VS Code Output panel

Symptoms

  • When the server starts, no logs are displayed in the Output tab.

Likely causes

  • In some cases, the first time you run an MCP server, logs don’t show up.

Fix

  • Restart the Grial MCP Server.

Verify

  • Logs are printed in the Output tab.
"XAML tools don’t work” (no pages injected / edits not applied)

Symptoms

  • Running a content tool does nothing or only partially updates files.
  • Screens/assets don’t appear in the project structure.

Likely causes

  • SetupServerSession was not run or used incorrect paths.
  • Solution/project files were moved or renamed.
  • IDE workloads are missing / project didn’t load correctly.

Fix

  1. Re-run SetupServerSession with correct workspacePath, solutionPath, and projectPath.
  2. Reopen the solution so the IDE reloads changes.
  3. Confirm the project builds from the CLI.

Verify

  • New XAML/C# files are present.
  • Build succeeds and pages are navigable.
“The catalog is not complete”

Symptoms

  • ListPagesCatalog returns only a few pages/templates.

Likely causes

  • The app linked to your session is Free. You need a Starter or Pro license to see more content.

Fix

  1. List the apps available to your user with ListGrialAppsIds.
  2. Select one that is Starter or Pro.
  3. Add the selected app to your session using AddAppIdToSession.

Verify

  • ListPagesCatalog now shows the full catalog available to your license tier.
Localization/translation didn’t create .resx files

Symptoms

  • LocalizeSolution or Translate finishes but no new .resx files appear.

Likely causes

  • Invalid locale codes.

Fix

  1. Ensure the base resources file exists and is writable.
  2. Retry Translate with valid BCP-47 locales (e.g., en-US, es-ES).

Verify

  • New AppResources.*.resx files exist with translated keys.

Error messages​

Match the message (or a close substring) to find the meaning and fix.

Message / PatternMeaningResolution
No active session foundTools called before session setupRun SetupServerSession with correct paths
Solution or project not foundInvalid .sln / .csproj pathFix paths; ensure files exist and are loaded
Failed to fetch catalogNetwork/auth/version issueCheck network; re-authenticate; update tooling
Write permission deniedWorkspace is read-onlyAdjust permissions; retry as appropriate
Invalid locale codeLocale not recognizedUse BCP-47 codes (e.g., en-GB, es-UY)

Contact support​

You can send the Grial MCP Server logs with your issue, and we’ll be glad to help.

  1. Reproduce the issue.
  2. Go to ~/.GrialMcp/logs and find your latest logs.
  3. Note your environment:
    • OS + version
    • IDE + version
    • .NET SDK version
  4. Include the exact tool call and parameters (omit secrets).
note

Never share credentials or private source code in diagnostics. Redact paths or project names if needed.

Reset & repair​

  • Reload the IDE after installing or updating tooling.
  • Re-run session setup with correct paths.
  • Clear and reinitialize by deleting the ~/.GrialMcp folder, then run “Grial: Add Local MCP Server” again to recreate configuration.

Avoid manually editing hidden session files unless a guide explicitly says so.