Reference
Troubleshooting
A failed EXPECT means the test failed — that’s working. This page is for “nothing is listening” and “I ran the wrong file.”
Two terminals
Quick start and POST use one terminal for snapapi mock and another for snapapi file.sapi. Activate the venv in both. A new tab doesn’t inherit it.
| You see | What it means | What to do |
|---|---|---|
command not found: snapapi | This shell has no venv (or the package is not installed). | source .venv/bin/activate (Windows: .venv\Scripts\activate), then pip install pysnapapi. Confirm with snapapi --version. |
externally-managed-environment | pip refused to install into system Python. | Create a venv first. See Install. |
Wrong project after pip install snapapi | That name is a different PyPI package. | Uninstall it. Install pysnapapi. The command is still snapapi. |
Connection refused / ERR | Nothing is listening on that port. | Start snapapi mock mock.json --port 8765 in the other terminal. Match URL: to that port. |
HTML 404 from SimpleHTTP | Port 8765 is some other Python server. | Stop it, or use --port 9876 and change URL:. |
Status code expected 200, got 404 on hello | HTTP reached a server that has no /users. | You are not hitting the hello mock.json. Check the port. |
Status code expected 201, got 404 on POST | The hello mock is still running. It has no POST route. | Stop it. Start examples/users/mock.json (or the mock pasted on the POST page). |
Status code expected 201, got 200 | The request worked. EXPECT does not match the response. | Failed test. Fix EXPECT or the server. Not an install problem. |
Undefined variable ${TOKEN} | No value for that name. | -D TOKEN=secret, or a .env file. The playground seeds TOKEN; the CLI does not. Hello world has no ${} — you opened a different suite. |
Undefined variable ${userId} | SAVE did not run, or the JSONPath missed. | Need SAVE: userId FROM $.id (or $.data.id) on a successful POST before you GET /users/${userId}. |
You wrote two TESTs but the summary says 1 passed | The first test is named in SETUP:, so it is treated as a helper. | Use HELPER: for setup. See Helpers. |
No such file or directory / exit 2 | Wrong path or folder. | Run from the folder that contains the .sapi file. tests/offline.snaptest is at tests/fixtures/offline.snaptest. |
Unknown keyword / exit 2 | Typo. Keywords are one token. | Fix the line. GET : with a space is not GET:. |
Unknown helper ${hmac()} / Unknown extension hmac() | Not a built-in, and no matching function in extensions/. | Add extensions/crypto.py and CALL: signature = crypto.generate_signature(${PAYLOAD}, ${HMAC_SECRET}). Don’t add IF / FOR to the file. |
CALL FAILED | The Python function raised, returned None, returned a disallowed type, or was async. | Fix the function in extensions/. The block names the function and the exception text. There is no traceback on purpose. |
| A request from a plugin isn’t in the report | You issued HTTP from Python. That bypasses SnapAPI’s HTTP engine. | Put the call in the .sapi file: POST: /users. CALL is for computation, not for driving the system under test. See CALL. |
Flakes only with --workers | A plugin used module-level mutable state. Those globals are shared across workers. | Make the function thread-safe, or don’t share globals. SnapAPI does not isolate Python modules. See three kinds of state. |
| Playground Live fetch fails, curl works | The browser enforces CORS. | Use the CLI for real hosts. Mock mode never leaves the tab. |
Editor
The language pack isn’t on the Marketplace. Install it from the repo — VS Code.