What to Do When It Won't Install or Run: Getting Started Troubleshooting
If your first request doesn't go through, it's most likely stuck in one of three places: the wrong Python environment, a misconfigured Key, or a request body that doesn't follow the rules. This lesson goes through common TypeSafe errors one by one, organized by their "original error text," giving the cause and fix for each—first do the 60-second quick check, then match your case. All Python errors were actually reproduced on typesafe-sdk v0.7.5 and Python 3.12.
What You'll Be Able to Do After This Lesson
- Pinpoint whether the environment, Key, or network is the problem with 3 commands in 60 seconds
- Match TypeSafe errors to their cases: which stage they occur in, what causes them, and how to fix them
- Understand what each of 7 HTTP status codes (400/401/413/415/422/429/529) is telling you
- Print
statusandrequest_idin your code usingexcept TypeSafeAPIError, so you can include evidence when asking for help - Know where to seek help: the console, official documentation, GitHub Issues, Discord
Your Current Predicament
- pip finished installing, but running it immediately gives
ModuleNotFoundError—did it not install, are you using the wrong Python, or did you install a wrong package with the same name? - You clearly set the Key, but still get 401, and you've re-copied it three times back and forth
- The error message is a blob of JSON, and you can't tell which field is the problem
When to Use This Approach
When you need to:
- Fix errors you're stuck on from the first request or alternative installation methods
- Before writing your own code, know where things tend to go wrong and what signals to look for when they do
And you don't want to:
- Post on forums and wait for replies the moment you hit an error—the 60-second quick check can save you most of that waiting
- Waste half a day changing code because you can't tell "the code is wrong" apart from "it's a Key/quota/server-side problem"
🎒 Preparation Before Starting
- Completed Installation and First Request (it's fine if you got stuck — this lesson is exactly about getting unstuck)
- A terminal with Bash (macOS / Linux / Windows WSL — the official commands are written for this environment)
- A browser logged in to the TypeSafe Console (you'll need to go back to it for Key-related questions)
Core Idea
Locate the stage first, then look at the error. A single Jev call has to pass four checkpoints, and each checkpoint's errors look different:
| Checkpoint | What to Check | Typical Errors |
|---|---|---|
| 1. Environment | Python version, whether the package was installed correctly | ModuleNotFoundError |
| 2. Authentication | Whether the Key exists and is correct | 401 / 403 (direct connection without an auth header, observed in testing) / TypeSafeError (thrown at client creation) |
| 3. Request Body | JSON rules, problem definition | 400 / 422 |
| 4. Server Side | Rate limiting, overload | 429 / 529 |
The SDK intercepts some errors locally. Starting from v0.7.1, an invalid Key throws TypeSafeError at client creation, so the request never goes out at all; a problem definition missing criteria is also intercepted locally. So for the same TypeSafeError, some never even reach the server—first distinguish "intercepted locally" from "returned by the server," because the troubleshooting directions are completely different.
Status code overview. Errors returned by the server carry standard HTTP status codes (docs/api/errors.md):
| Status Code | Meaning | In One Sentence |
|---|---|---|
400 Bad Request | Violates request rules (UTF-8, nesting depth, non-finite numbers, malformed compressed body); max_tokens_exceeded = exceeds context | modify request body |
401 Unauthorized | Key missing or invalid | check your Key |
413 Payload Too Large | Request body exceeds 32 MiB | reduce the size |
415 Unsupported Media Type | Content-Encoding unsupported or compressed more than one layer | change the compression |
422 Unprocessable Entity | Field validation failed, body indicates the field | fill in the field |
429 Too Many Requests | Rate limit exceeded | back off and retry |
529 Overloaded | TypeSafe temporarily overloaded | back off and retry |
💡 include the request_id when asking questions
The SDK's API error object has request_id (from the x-typesafe-request-id response header). Include it when giving official feedback, and the other side can look up that request directly. Discord community entrance: discord.gg/typesafe.
First-pass troubleshooting: 60-second quick check
Run the three commands in order, verifying the package, Key, network, and authentication in turn; each one has its expected output labeled.
# 1. 包装对了吗?——应该看到 0.7.5(或更高)
.venv/bin/python -c "import typesafe_sdk; print(typesafe_sdk.__version__)"
# 若报 ModuleNotFoundError:装的环境和跑的环境不是同一个,或装错了包(见下方排错)
# 2. Key 设置了吗?——应该看到完整 Key 字符串
echo "$TYPESAFE_API_KEY"
# 空的:export TYPESAFE_API_KEY="your-api-key" 再跑(新开终端要重新 export)
# 3. Key 真的有效吗?——应该看到 HTTP 401(说明网络通、你还没用真 Key)
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"
# 200 = 认证通过;401 = Key 无效(见下方排错)You should see: command 1 prints the version number, command 2 prints the Key, and command 3 returns 200 (when the Key is valid) or a recognizable status code. Fix whichever step fails.
Common problem troubleshooting
Environment and installation issues
"ModuleNotFoundError: No module named 'typesafe_sdk'"
Cause: the package was installed into .venv, but the run uses the system Python (or another environment) — the two interpreters are not the same one. Another possibility: pip install typesafe installed a wrong package with the same name (see the next section).
Fix:
- Always run with the interpreter inside the venv (as in the official examples):
.venv/bin/python route_ticket.py- Or activate the environment first and then run (general venv usage):
source .venv/bin/activate
python route_ticket.py- If it still doesn't work, confirm the package is really installed: run
.venv/bin/pip install typesafe-sdkagain and check that the output containsSuccessfully installed.
You should see: three lines of output technical / 0.67 / 0.99 (values vary with the version; the structure just needs to match).
"ImportError: cannot import name 'TypeSafeClient' from 'typesafe'"
Cause: pip install typesafe (missing the -sdk) does not raise an error — what it installs is an unrelated third-party library with the same name, typesafe 0.9.1 ("formal type asserting decorators", by Krister Hedfors, with no relation whatsoever to TypeSafe AI), which naturally contains no TypeSafeClient. So from typesafe import TypeSafeClient raises an ImportError; in the same environment, import typesafe_sdk raises the ModuleNotFoundError shown above.
Fix:
- Uninstall the wrongly installed package and install the correct one (the install name uses hyphens
typesafe-sdk):
.venv/bin/pip uninstall -y typesafe
.venv/bin/pip install typesafe-sdk- Verify the import (the import name uses underscores
typesafe_sdk):
.venv/bin/python -c "from typesafe_sdk import TypeSafeClient; print('ok')"You should see: ok; the pip output contains Successfully installed ... typesafe-sdk-0.7.5.
Python version below 3.10
Cause: the official SDK requires Python 3.10 or higher (docs/introduction/quickstart.md: "Requires Python 3.10 or later", PyPI metadata requires-python = ">=3.10").
Fix:
- Check the current version:
python3 --version- If the version is below 3.10: install 3.10+ and rebuild the venv with it (an old venv is bound to the old interpreter and must be rebuilt):
python3.10 -m venv .venv # 或你装好的更高版本
.venv/bin/pip install typesafe-sdkYou should see: .venv/bin/python --version prints Python 3.10 or higher.
"zstd compression requires Python 3.14+ or the typesafe-sdk[zstd] extra."
Cause: you explicitly passed compression='zstd', but on Python < 3.14 zstd support is in an optional extra, which the default installation does not include.
Solution (two options):
Option 1 (install the extra, recommended):
.venv/bin/pip install "typesafe-sdk[zstd]"Option 2 (disable compression):
client = TypeSafeClient(compression=False)⚠️ v0.7.5 enables compression by default
Starting from v0.7.5 the SDK uses zstd compression by default for request bodies ≥1 KiB (the official changelog notes: unofficial APIs may not support this immediately). The official command to "ensure zstd is available" is uv add "typesafe-sdk[zstd]". In testing, the default installation (without the extra) does not raise an error when creating objects — compression is used if available and skipped if not; only explicitly requesting zstd raises this error.
"ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using pip install httpx[socks]."
Cause: a SOCKS proxy is configured in the environment (proxy environment variables); the SDK's HTTP layer (httpx2) needs the socksio package to use SOCKS, which the default installation does not include — the error is raised when creating the client, and no request can be sent.
Solution: install socksio and then rebuild the client:
.venv/bin/pip install socksioYou should see: the client is created successfully (tested: after installing socksio, with the same SOCKS proxy in place, the client is created normally). The pip install httpx[socks] suggested in the error message is a generic httpx-family hint; the SDK uses httpx2, so installing socksio directly is enough.
pip fails to install / package not found (network-related)
Cause: the official documentation does not provide a TypeSafe-specific solution for installation failures; common cases are no network access to the PyPI origin, or a misspelled package name resulting in a different package being installed (see above).
Fix:
- First rule out a package name issue: the correct command is
pip install typesafe-sdk, and a successful install output containsSuccessfully installed ... typesafe-sdk-0.7.5. - Handle network issues according to your environment (proxies and mirror sources are general pip knowledge; the official documentation gives no TypeSafe-specific solution).
- On Python < 3.10 pip may refuse to install outright (official minimum version 3.10); fix the version first per the previous item.
Authentication and Key issues
"No API key was provided. Pass api_key or set the TYPESAFE_API_KEY environment variable."
Cause: neither the api_key parameter was passed nor the environment variable was set — the SDK blocks this when creating the client. Note: passing an empty Key explicitly does not fall back to the environment variable; api_key='' is the same as not passing it.
Fix:
- Environment variable approach (officially recommended; no secrets written in code):
export TYPESAFE_API_KEY="your-api-key"- Or pass it explicitly in your code:
from typesafe_sdk import TypeSafeClient
client = TypeSafeClient(api_key="your-api-key")You should see: the client is created successfully, with no more TypeSafeError thrown.
"Cannot authenticate with the server. Please check your API key and try again."
Cause: HTTP 401 — the request reached the server, but the Key is invalid. The SDK throws TypeSafeAuthenticationError (str(e) looks like POST https://api.typesafe.ai/v1/systemone: 401 Cannot authenticate... (request_id=req_...)).
Fix:
- Go back to the Keys page in the console and copy the Key again (hand-copying is error-prone).
- Set it again and verify:
export TYPESAFE_API_KEY="<重新复制的Key>"
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"You should see: the command returns 200 and a JSON ({"models":[...]}, listing the models and aliases available to your account).
"Must supply an API key! Check your request and try again."
Cause: when connecting directly via HTTP (curl / fetch), the request did not carry the Authorization header at all — the API rejects it outright and returns 403 (in testing: requesting /v1/models without any auth header yields 403 and this message; the official status code table does not list 403, and the corresponding SDK exception class is TypeSafePermissionDeniedError). SDK users generally won't hit this: once the Key is configured, the SDK sends the header automatically.
Fix: send the request with the Bearer auth header:
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"You should see: with a valid Key, it returns 200 and {"models":[...]}; with an invalid Key, it becomes 401 (see the previous item).
"API key must contain only printable ASCII characters without whitespace."
Reason: The key contains internal spaces, control characters, or non-ASCII characters (the SDK only strips leading and trailing whitespace; problematic characters inside are rejected outright).
Fix: copy the Key again in full — don't splice or hand-edit it. When pasting, be careful not to introduce a line break in the middle.
Request body rejected (400 / 413 / 415 / 422)
"422 Unprocessable Entity"
Cause: request body field validation failed — for example, a missing state or a field in the wrong format. The request passed the SDK's local validation, and after being sent to the server, the server returned 422; the response body indicates the field: loc is the location, msg is the reason (e.g., Field required).
Fix:
- In your code, catch
TypeSafeAPIErrorand print the full body to inspect the field (the problem in this example includesinstructions, so it passes local validation and actually reaches the server):
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print(error.status) # 服务器返回的状态码;422 = 字段校验失败
print(error.body) # 422 时里边 loc/msg 指明哪个字段
print(error.request_id) # 反馈给官方时带上- Fill in the field indicated by
locand send again.
You should see: a valid request returns results normally; if the server returns 422, error.body contains field-level hints like loc: ["body", "state"], msg: "Field required" (from the official OpenAPI examples). The exact trigger for a server-side 422 depends on which rule the request violated — go by what the body actually returns.
💡 Many 422 never even reach the server
If you omit instructions when constructing Noul(), the SDK throws TypeSafeError: Noul question "q2" has neither instructions nor criteria; at least one is required. locally; a Score/Choice question missing criteria is also intercepted locally: TypeSafeError: Question "broken" requires "criteria". (the broken there is your own question key name). What gets thrown is the TypeSafeError base class, not TypeSafeAPIError — just fix your code; no need to suspect the network.
"413 Payload Too Large"
Cause: the request body exceeds 32 MiB (headers don't count); both the compressed and decompressed sizes are subject to this limit.
Fix: trim state, or split large materials across multiple requests.
"415 Unsupported Media Type"
Cause: Content-Encoding uses an unsupported encoding, or compression is layered more than once (gzip / x-gzip / zstd — only one layer each).
Fix: when connecting directly via HTTP, use only a single layer of compression; SDK users generally won't hit this (the SDK handles compression itself).
"max_tokens_exceeded"
Cause: the request exceeds the model's context limit — 64k per-request (state + all questions) / 32k per-question (state + a single question), both including state.
Fix (three options, from lowest to highest cost):
Option 1 (trim materials, recommended): filter the state and send only the fields the question needs — saves money and improves accuracy.
Option 2 (long context): add a request header to the requests that need it (both contexts become 262k, slower and less accurate, price unchanged):
-H "TypeSafe-Danger-Zone-Long-Context: true"Option 3 (reduce the number of questions or split requests): the per-request limit covers all questions — if there are too many, split first.
Rate limiting and server-side issues
"429 Too Many Requests"
Cause: you exceeded the organization-level rate limit (dual metrics of tokens/s + requests/s, counted per organization).
Fix:
- Use the SDK (exponential backoff retries are built in by default, and it honors
retry-after) — you don't have to do anything:
from typesafe_sdk import RetryPolicy, TypeSafeClient
# 默认就是自动重试;按需自定义(默认 max_retries=2、退避 0.5→5s、总预算 30s)
client = TypeSafeClient(retry=RetryPolicy(max_retries=3))- Only if you connect directly via HTTP do you need to write your own exponential backoff — don't immediately resend as-is.
- Check your quota on the rate-limits page in the console; if you need higher limits, go custom/enterprise (request form support.typesafe.ai/forms/rate-limit-increase-request).
"529 Overloaded"
Cause: TypeSafe is temporarily overloaded; like 429, it belongs to the "wait and retry" category.
Fix: same as 429 — the SDK retries with automatic backoff; if connecting directly, write your own backoff. If it persists, check Discord or the status page to see whether it's a widespread outage.
Agent Skill issues
"The agent isn't using the skill"
Cause: the coding agent didn't load the TypeSafe skill — it wasn't invoked by name, it was installed for the wrong agent, or the agent wasn't restarted after installation.
Fix (the three official steps from docs/agent-skill.md):
- In the Claude Code plugin, invoke
/typesafe:typesafe-aidirectly; for other agents, mention"use the TypeSafe skill"by name in the prompt. - Still not working: confirm that the agent you selected during installation is the one you're actually using (
npx skills addinstalls at the project level by default; add-gto install globally). - Restart the agent and try again.
"The agent invents request or response fields"
Cause: the skill version is outdated and it was taught the old interface.
Fix: update the skill and retry (Claude Code):
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-aiThen restart Claude Code or run /reload-plugins.
Still not working?
Gather evidence before asking. A minimal reproducible code snippet + the verbatim error + request_id beats a hundred sentences of description:
# catch_report.py:复现问题并打印关键信息
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print("status:", error.status)
print("body:", error.body)
print("endpoint:", error.endpoint)
print("request_id:", error.request_id) # 提问必带
except Exception as error: # 本地拦截(Key/问题定义),没到服务器
print(type(error).__name__, str(error))If you need more detailed logs, raise the SDK's log level (auth headers are redacted, but request/response bodies are not — be careful not to post sensitive content in public places):
export TYPESAFE_LOG_LEVEL=debugWhere to ask:
| Channel | When to go there |
|---|---|
| Console Keys / rate-limits page | Key and quota issues — check here first |
| Official error documentation | Status code semantics and rule details |
| API quick reference | This site: quick reference for requests/responses/status codes |
| GitHub Issues | SDK defects (Python SDK repository) |
| Discord community | The officials say "Tell us what you build, and what breaks" — if it breaks, just report it |
Checkpoint ✅
- 60-second quick check: I have run all three commands and know which step it got stuck at
- I can distinguish locally intercepted
TypeSafeError(Key, problem definition) from server-returnedTypeSafeAPIError - When I get 401, I go back to the console to re-copy the Key, then verify with curl
/v1/models - For 429/529 I know the SDK automatically retries with backoff by default, so I don't need to write it myself
- When asking a question I include a minimal reproduction and the
request_id
FAQ
How do I set the Jev key (API Key)?
The official recommendation is to use an environment variable and not put the key in code: export TYPESAFE_API_KEY="your-api-key"; note that a newly opened terminal needs the export again. You can also pass it explicitly in code: TypeSafeClient(api_key="your-api-key"). Note that explicitly passing an empty Key does not fall back to the environment variable; api_key='' is equivalent to not passing one — see "Authentication and Key Issues" above.
The Key is set but I still get 401 — what should I do?
401 means the request reached the server but the Key is invalid. Go back to the console Keys page and copy the Key again in full (manual transcription is error-prone; the Key must not contain internal spaces or non-ASCII characters). After setting it again, verify with a curl request to /v1/models; a return of 200 means the Key is valid.
Where is the official documentation for TypeSafe AI?
For status code semantics and rule details, see the official error documentation docs.typesafe.ai/api/errors.md. For Key and quota issues, first self-check in the console; for SDK defects, file GitHub Issues; if things are broken you can go straight to Discord to report.
Lesson summary
✅ Start troubleshooting by pinpointing the stage: environment (Python/packages) → authentication (Key) → request body (rules) → server side (rate limiting/overload).
✅ All the key TypeSafe errors covered: ModuleNotFoundError use the right interpreter, 401 re-copy the Key, 422 check the loc field, 429/529 leave it to the SDK's default retries.
✅ How to ask: minimal reproduction + the original error text + request_id, then go to Discord or GitHub Issues.
Key facts recap:
| Signal | Which layer | First step |
|---|---|---|
ModuleNotFoundError | Environment | Run with .venv/bin/python |
ImportError: cannot import name 'TypeSafeClient' from 'typesafe' | Environment (wrong package installed) | Uninstall typesafe and install typesafe-sdk instead |
Creating the client throws TypeSafeError | Authentication (local) | Set TYPESAFE_API_KEY |
401 + TypeSafeAuthenticationError | Authentication (server) | Go back to the console and re-copy the Key |
422 | Request body | Check the body's loc/msg |
429 / 529 | Server side | Leave it to SDK retries; write backoff yourself for direct connections |
Next lesson preview
That wraps up getting-started troubleshooting — your environment is now stable. Next, move on to everyday usage: master the five ways of asking Jev questions.
You will learn:
- State: what kind of material to give Jev
- How to choose among the three question types: Choice / Score / Noul
- Confidence: how to use thresholds for branching
- How to send images in a request