Troubleshoot SnapCode

Resolve issues with SnapCode installation, sign-in, startup, and pipeline execution.

Messages in quotes are what the session start or the command prints.

Downloading the `snaplogic` CLI (first session)


What you see	Reason	Resolution
`[x] snaplogic CLI — not available` and "could not set up the slpy CLI — `address` answered HTTP `code`. That is the download service, not your machine or network."	The CLI download service on your control plane returned an error.	Check that `SNAPLOGIC_BASE_URL` is your control plane URL. If it is, start a new session later; if the error persists, contact SnapLogic support with the HTTP code.
"could not set up the slpy CLI — the CLI could not be downloaded. Check network access to `address`."	The machine can't reach the download service (proxy, firewall, VPN, or offline), or `SNAPLOGIC_BASE_URL` is mistyped.	Check the address in the message, allow HTTPS to it, then start a new session.
"this is a TLS trust problem, NOT a credentials/URL problem" or `CERTIFICATE_VERIFY_FAILED`	Your Python has no usable CA trust store. Common on python.org macOS builds where Install Certificates.command was never run, or a corporate proxy presents a root CA your Python can't see.	The plugin recovers on its own when `truststore` or `certifi` are importable. Otherwise: python.org macOS build: run `"/Applications/Python 3.x/Install Certificates.command"` Corporate proxy: add `export SSL_CERT_FILE="$(python3 -c 'import certifi; print(certifi.where())')"` to your shell profile, then open a new terminal and restart Claude Code.
"the `snaplogic` CLI was downloaded but will not run on this machine"	The downloaded build does not match the machine (OS or CPU architecture).	Contact SnapLogic support with your OS and architecture (`uname -sm` on macOS/Linux, or `echo $env:PROCESSOR_ARCHITECTURE` on Windows).
"the published `snaplogic` CLI is older than the plugin expects and cannot install slpy"	The published CLI predates the plugin.	Nothing to fix locally; it needs a newer CLI release.

Address and sign-in


What you see	Reason	Resolution
`[x] Sign-in — no SnapLogic address: SNAPLOGIC_BASE_URL is not set`	No address configured.	Set `SNAPLOGIC_BASE_URL` and restart Claude Code. Refer to Set your SnapLogic credentials.
"SNAPLOGIC_BASE_URL: `value` must be written as `https://host`"	The address has no `https://`, a trailing `/`, or capital letters. The CLI and the SnapLogic MCP server use it exactly as written.	Set it to the form the message shows, open a new terminal, restart Claude Code.
"is not a SnapLogic address"	`SNAPLOGIC_BASE_URL` is not a SnapLogic control plane address; the message lists the domains allowed.	Set it to your control plane URL.
"currently signed in to `address`, and only one pod can be signed in to at a time"	`snaplogic auth login` was run for a new control plane while still signed in to another.	Sign out of the old one first, then sign in: `! SNAPLOGIC_BASE_URL=https://old-host snaplogic auth logout`, then `! snaplogic auth login`.
`[x] Sign-in — snaplogic auth status: not signed in to host`, with `[x] SnapLogic MCP — not signed in`	No password in the environment and no browser sign-in, or the sign-in expired (unused for a while, past its maximum lifetime, or signed out).	Sign in as noted in the checklist, then start a new session.
`[x] Sign-in — snaplogic auth status did not answer`	The `snaplogic` CLI did not run, or gave an answer the plugin could not read.	Run `! snaplogic auth status` in Claude Code to see its error, then start a new session.
`snaplogic auth login` ends with "timed out waiting for the browser callback"	The browser part has a 3-minute time limit.	Run `! snaplogic auth login` again and finish in the browser within 3 minutes (it returns to `127.0.0.1`).
Claude was asked to sign you in	Sign-in opens your browser and waits for you to act, so you must run it, not Claude.	Type `! snaplogic auth login` at the prompt yourself.
The browser goes straight to Authorize SnapLogic CLI without a sign-in page	You are already signed in to SnapLogic in that browser.	Expected. Check the "signed in as" line. For a different account, sign out of SnapLogic in that browser or use a private window.
"Already signed in to `address` as `user`"	A valid sign-in already exists.	Expected. To sign in again, run `! snaplogic auth logout` first.
"SNAPLOGIC_API_USER and SNAPLOGIC_API_PASS are for `user` on `address`, but a login for `user` on `address` is also saved"	A password and a browser sign-in are both set, for a different control plane or user. The CLI stops rather than pick one.	Use one or the other: unset both `SNAPLOGIC_API_USER` and `SNAPLOGIC_API_PASS` to use browser sign-in, or run `! snaplogic auth logout` to remove the saved sign-in.
"SNAPLOGIC_API_USER is set but SNAPLOGIC_API_PASS is not set" (or the reverse)	Only one of the password pair is set, often left over from a previous setup.	Set both to use a username and password, or clear the one that is set to use browser sign-in. Open a new terminal, restart Claude Code.
"credentials file `path` is open to other users"	The file holding your browser sign-in can be read by other users on this machine.	Run `chmod 600 path` as the message says.

Installing `slpy`


What you see	Reason	Resolution
`[x] slpy — not installed` with a sign-in note underneath	`slpy` installs through your sign-in, and there is none yet.	Sign in (refer to Address and sign-in above).
"uv is not installed: install it from https://docs.astral.sh/uv/getting-started/installation/ and run this again"	`uv`, which installs `slpy`, is missing.	Install `uv` from that page, open a new terminal, start a new session.
"could not install the slpy CLI. The CLI reported: … Authentication required."	Your `SNAPLOGIC_API_PASS` was rejected.	Check it by signing in to the SnapLogic UI. Fix it, open a new terminal, restart Claude Code. Repeated failures can lock the account.
"no organization for this deployment: set SNAPLOGIC_ORG_NAME, or pass --org"	Username and password set without `SNAPLOGIC_ORG_NAME`.	Set it, spelled exactly `SNAPLOGIC_ORG_NAME`. A misspelled variable name is silently ignored. Open a new terminal, restart Claude Code.
"no organization recorded for this deployment: run `snaplogic auth login --org name` to record one, or pass --org"	Browser sign-in without a default organization.	Run `! snaplogic auth login --org name`. This sets the default organization without reopening the browser if you are already signed in.
"SNAPLOGIC_ORG_NAME is `A` but the saved login's default organization is `B`"	`SNAPLOGIC_ORG_NAME` is left over from a password setup, and your browser sign-in recorded a different organization.	Unset `SNAPLOGIC_ORG_NAME`, or run `! snaplogic auth login --org A` to make it the default.
`slpy` is still missing after signing in	The installer endpoint on your control plane can't be reached (proxy or firewall).	The machine must be able to reach your SnapLogic address. Start a new session.

After changing your password


What you see	Reason	Resolution
"Authentication required", MCP 401s, or the account locks soon after a password change	Claude Code sessions opened before the change still use the old password.	Close sessions opened before the change and start new ones from a terminal with the new password.

SnapLogic MCP server


Symptom	Resolution
`plugin:snapcode:snaplogic` does not appear in `/mcp`	The SnapCode plugin is not installed or not enabled. Run `claude plugin list` and check that `snapcode@snapcode` is installed and enabled. If it is not, refer to Install SnapCode. After installing or updating while a session is open, run `/reload-plugins`.
MCP shows "not authenticated" or a 401 error	If you're using browser sign-in (SSO): your sign-in has expired or you aren't signed in. Run `! snaplogic auth login` in the Claude Code session, then run `/mcp` to reconnect. If you're using a username and password: credentials are missing or incorrect, or they're set in a different shell than the one running Claude Code. Verify the credentials and restart Claude Code.
MCP shows a 404 or OAuth error	Claude Code fell back to its own OAuth, which happens only when the plugin's auth helper (`bin/mcp_headers.py`) did not run or failed. Run it by hand in the same shell: macOS / Linux / Git Bash: `python3 ~/.claude/plugins/cache/snapcode///bin/mcp_headers.py` Windows PowerShell: `python (Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache\snapcode\\\bin\mcp_headers.py").FullName` It should print `{"X-MCP-Tool-Profile": "snapcode", "Authorization": "..."}`: `Bearer` plus a token means your browser sign-in is used, `Basic` means your password, and `Bearer snapcode-not-signed-in` means neither was found. Sign in or set `SNAPLOGIC_API_USER` and `SNAPLOGIC_API_PASS` and restart Claude Code. The output contains your credential: do not paste it anywhere.

Other


Symptom	Resolution
`ENOENT`: Bun could not find a file on `plugin marketplace add` or `install`	Usually caused by a stale `CLAUDE_CONFIG_DIR` pointing at a directory that no longer exists. Check and clear it, then retry: macOS / Linux: `echo $CLAUDE_CONFIG_DIR` then `unset CLAUDE_CONFIG_DIR` Windows PowerShell: `$env:CLAUDE_CONFIG_DIR` then `Remove-Item Env:\CLAUDE_CONFIG_DIR`

Skill not recognized


Symptom	Reason	Resolution
SnapCode skill is not available when you start Claude Code	The SnapCode plugin is not installed or not enabled.	Run `claude plugin list` and check that `snapcode@snapcode` is installed and enabled. If it is not, refer to Install SnapCode. After installing or updating while a session is open, run `/reload-plugins`.

Pipeline validation and execution errors


Symptom	Reason	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.

Checks when nothing above fits

! which slpy should point inside ~/.claude/plugins/ (not an old ~/.local/bin/slpy).
! slpy --help should print the usage.
/snaplogic should list snaplogic-slpy-gen, snaplogic-deploy, agent-pipelines, and mcp-server-pipelines.