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 credentials are set: 
    echo $AWS_ACCESS_KEY_ID
    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.
pygen shows in /mcp but tools fail Docker is not running, or AWS credentials are missing
  • Check that Docker Desktop is running: 
    docker ps
  • Verify your AWS credentials are set in .env. Snap discovery (the pygen_query_snap_examples tool) requires AWS credentials. The pygen_get_all_snap_names tool does not require them — if only that tool fails, Docker may not be running.

Skill not recognized

Symptom Cause Resolution
SnapCode skill is not available when you start Claude Code You are not running claude from the sl-procode directory, or the global install has not been run
  • Run claude from inside the sl-procode 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.
  3. As a quick fix without rebuilding, export credentials directly inside the container terminal: 
    export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
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.