Troubleshoot SnapCode

Resolve common issues with SnapCode installation, startup, and pipeline execution.

MCP servers not connected

Symptom Cause Resolution
/mcp shows No MCP servers configured Credentials are missing or the terminal was not restarted after setting up .env.
  1. Verify your SnapLogic credentials are set: 
    echo $SNAPLOGIC_BASE_URL
    If the output is empty, ensure your .env file is complete and open a new terminal before running claude.
  2. Run /doctor inside Claude Code for MCP diagnostics, including missing environment variables.
  3. If you were prompted about a new MCP server and dismissed it, reset and retry: 
    claude mcp reset-project-choices
claude
    When prompted, select Use this and all future MCP servers in this project.
snaplogic is connected but tools return a 401 error SnapLogic credentials are missing or incorrect in .env.
  1. Verify that SNAPLOGIC_API_USER and SNAPLOGIC_API_PASS are set correctly in .env.
  2. Confirm you can log in to your SnapLogic control plane with those credentials.
  3. Re-run the installer to re-template the MCP URL:

    macOS / Linux: ./install.sh docker

    Windows: .\install.cmd docker

Skill not recognized

Symptom Cause Resolution
SnapCode skill is not available when you start Claude Code You are not running claude from the SnapCode directory, or the global install has not been run
  • Run claude from inside the SnapCode directory.
  • Or run the global installer to make SnapCode available from any directory. See Use SnapCode from any directory.
  • Verify the skill file exists: 
    ls .claude/skills/snaplogic-slpy-gen/SKILL.md
    If missing, pull the latest repo changes (git pull).

Docker image issues

Symptom Cause Resolution
Docker image not found during install Image has not been pulled yet

Run the installer again. It pulls the image automatically.

macOS / Linux: ./install.sh docker

Windows: .\install.cmd docker
403 Forbidden or denied when pulling the image GitHub PAT is stale, wrong, or lacks read:packages scope. Note: a successful docker login does not confirm package access — the access check happens at pull time.

The installer detects a failed pull, clears the cached token, and prompts for a new one. Paste a valid token when asked. Ensure your token is:

  • A classic PAT (not a fine-grained token)
  • Created with the read:packages scope
  • From a GitHub account that has access to the SnapCode repository

To reset manually:

macOS / Linux: 
rm ~/.procode-token && docker logout ghcr.io
Windows: 
del %USERPROFILE%\.procode-token && docker logout ghcr.io

Then run the installer again. If your account lacks access, ask a repository administrator to grant read access to the package.

VS Code Dev Container issues

Symptom Cause Resolution
Credentials are empty inside the Dev Container .env file is missing or the container has not been rebuilt after creating it
  1. Confirm .env exists in the repo root: 
    cp .env.example .env
  2. Rebuild the container: press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows), then select Dev Containers: Rebuild Container.
Dev Container fails to start on Windows Workspace is on a Windows drive path, which causes path and socket issues

Use one of these approaches:

  • Recommended: Clone the repository inside WSL (for example, under \\wsl$\Ubuntu\home\<you>\), open it with VS Code's WSL remote, then select Reopen in Container.
  • Alternative: Skip the Dev Container and use the Terminal environment instead. Run .\install.cmd docker and use claude from a regular terminal window.

Pipeline validation and execution errors

Symptom Cause Resolution
Validation fails after deploy with a snap or field error A snap parameter is missing, incorrectly typed, or references a field that does not exist Tell SnapCode what the error means and what the correct value should be. For example: 
Fix it — subtotal should be qty × unit_price
SnapCode edits the .py file, retranslates, redeploys, and revalidates automatically.
Pipeline passes local execution but fails Platform validation or execution Difference in behavior between the local execution engine and the SnapLogic Platform This is a non-conformance between the local engine and the Platform. Report it to the SnapCode team with the pipeline file and the exact error so it can be investigated.