📘 תיעוד 126

פתרון תקלות ב-Agent SDK

תקן שגיאות ב-Agent SDK לפי ההודעה המדויקת שאתה רואה, כולל הסיבה והתיקון לכל שגיאה ב-SDK של TypeScript ושל Python.

הרשומות בדף זה מסודרות לפי השגיאה שאתה רואה. כל אחת מציינת את הסיבה ומה לעשות.

#הפעלת ה-CLI

#CLINotFoundError: Claude Code not found

ה-SDK של Python מפעיל את ה-CLI של Claude Code כתהליך משנה. כאשר הוא אינו מצליח למצוא קובץ הפעלה של claude, החיבור נכשל עם CLINotFoundError:

Claude Code not found at: /your/configured/path

ההודעה כוללת את הנתיב המוגדר כאשר אתה מגדיר את ClaudeAgentOptions(cli_path=...) והוא מצביע על קובץ חסר. ללא cli_path, ה-SDK מחפש ב-PATH שלך ובמיקומי התקנה נפוצים, וההודעה כוללת הוראות התקנה עבור הפלטפורמה שלך.

כדי לתקן זאת:

1. התקן את Claude Code אם אינו מותקן. ראה התקנת Claude Code עבור הפקודה המתאימה לפלטפורמה שלך.
2. אם הגדרת את cli_path, ודא שהקובץ קיים ושהוא אכן קובץ ההפעלה של claude.
3. אם אתה מסתמך על פתרון באמצעות PATH, ודא ש-claude --version פועל באותה סביבה שבה היישום שלך רץ. תהליכים שאתה מפעיל מחוץ למעטפת (shell), כמו למשל מתוך IDE או מנהל שירותים, רצים לעיתים קרובות עם PATH שונה.

ה-SDK של TypeScript מחפש את ה-CLI בחבילת הפלטפורמה המצורפת שלו ובנתיב שהגדרת ב-pathToClaudeCodeExecutable. התאם להודעה שאתה רואה:

• Native CLI binary for <platform>-<arch> not found: חבילת הפלטפורמה המצורפת חסרה, לרוב מכיוון שההתקנה דילגה על תלויות אופציונליות. התקן מחדש את @anthropic-ai/claude-agent-sdk מבלי לדלג על תלויות אופציונליות, או כוון את pathToClaudeCodeExecutable אל התקנה מקומית. בקובץ הפעלה יחיד שנבנה באמצעות bun build --compile, לאותה הודעה יש סיבה ותיקון שונים. ראה קימפול לקובץ הפעלה יחיד.
• Claude Code native binary not found at <path> או Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?: הקובץ בנתיב שנמצא חסר, או שלתהליך אין הרשאת גישה אליו. ודא שהקובץ קיים בנתיב זה ושלתהליך יש הרשאה לגשת אליו.

#CLIConnectionError: Refusing to execute batch script

ב-Windows, החיבור נכשל עם CLIConnectionError כאשר נתיב ה-CLI שבו ה-SDK של Python משתמש הוא סקריפט אצווה מסוג .bat או .cmd, כולל מעטפת הגישור claude.cmd שנוצרת בהתקנת npm:

Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

הסירוב הוא הקשחת אבטחה מכוונת, ולא התקנה פגומה. מערכת Windows מריצה סקריפטים של אצווה על ידי שכתוב הפעלת התהליך לקריאת cmd.exe /c, ו-cmd.exe מפענח מחדש את כל שורת הפקודה בזמן הריצה, כך שערך של ארגומנט יכול להריץ פקודות מוזרקות.

מרבית ההתקנות ב-Windows לעולם אינן מגיעות לשגיאה זו. קובץ ה-wheel עבור Windows x64 של claude-agent-sdk כולל claude.exe מובנה, וה-SDK מעדיף את ה-CLI המצורף, לאחר מכן כל claude.exe מקומי שהוא מצליח לאתר, ורק אז נסוג למעטפת גישור של סקריפט אצווה. אתה רואה את הסירוב בשני מקרים:

• הגדרת את ClaudeAgentOptions(cli_path=...) לקובץ .bat או .cmd, כמו למשל מעטפת הגישור claude.cmd של npm.
• בהתקנה שלך אין claude.exe מצורף או מקומי, לדוגמה התקנה מקוד מקור ב-Windows ARM64 שבה ה-claude היחיד ב-PATH שלך הוא מעטפת הגישור של npm.

כדי לתקן זאת, ספק ל-SDK קובץ הפעלה מקומי במקום סקריפט אצווה:

1. אם הגדרת את ClaudeAgentOptions(cli_path=...), כוון אותו לקובץ claude.exe או הסר את האפשרות. ה-SDK מדלג על שלב האיתור כל עוד cli_path מוגדר, ולכן התקנה מקומית לבדה לא תוכל להיכנס לתוקף.
2. התקן את Claude Code באופן מקומי ב-PowerShell: irm https://claude.ai/install.ps1 | iex
3. ב-Windows x64, התקן את ה-wheel של claude-agent-sdk, שמצרף עמו את claude.exe.

לפני גרסה 0.2.124 של claude-agent-sdk, ה-SDK של Python הפעיל סקריפטים של אצווה דרך cmd.exe ללא בדיקה זו.

#CLIConnectionError: Failed to start Claude Code

ה-SDK מצא קובץ בנתיב שנמצא אך לא הצליח להפעיל אותו. Python מעלה כשלים אלה כ-CLIConnectionError. ב-TypeScript מתקבלת דחייה של איטרציית ההודעות עם שגיאה שאינה נושאת מחלקת SDK. הטבלה להלן ממפה כל הודעה למה שהיא מציינת. התאם להודעה שאתה רואה:

בשני ה-SDK, הסיבה הנפוצה היא נתיב שנמצא ומצביע על משהו שאינו יכול לרוץ, כגון קובץ טקסט, ספרייה או קובץ ללא הרשאת הפעלה. קרא את הצעת ה-libc בהודעת הקובץ הבינארי כסיבה אפשרית אחת.

כדי לתקן זאת בכל אחד מה-SDK:

1. ודא שהנתיב המוגדר מצביע על קובץ ההפעלה claude עצמו ושיש לקובץ הרשאת הפעלה.
2. אם אינך זקוק לנתיב מותאם אישית, הסר את cli_path ב-Python או את pathToClaudeCodeExecutable ב-TypeScript, כדי שה-SDK ימצא CLI בעצמו, תוך העדפת העותק המצורף שלו.
3. כאשר הקובץ הבינארי שנכשל הוא העותק המצורף של ה-SDK בתוך תמונת קונטיינר, התקן מחדש את ה-SDK במהלך בניית התמונה כדי שהקובץ הבינארי המצורף יתאים לפלטפורמה של הקונטיינר, או בנה מחדש את התמונה עבור הארכיטקטורה שעליה היא רצה. הסיבה הנפוצה היא קובץ בינארי שאינו תואם לארכיטקטורה או ל-libc של הקונטיינר, או קובץ שאיבד את הרשאת ההפעלה שלו במהלך בניית התמונה.

#CLIConnectionError: Not connected

קריאה למתודה של ClaudeSDKClient ב-Python לפני שהלקוח התחבר, או לאחר שהתנתק, מעלה CLIConnectionError עם הודעה זו:

Not connected. Call connect() first.

עשה מה שההודעה אומרת. קרא ל-await client.connect() לפני כל מתודה אחרת של הלקוח, או פתח את הלקוח באמצעות async with ClaudeSDKClient() as client:, אשר מתחבר בעת הכניסה.

#יציאת תהליך ה-CLI

הרשומות בסעיף זה מתייחסות למצב שבו תהליך Claude Code הסתיים בזמן שהיישום שלך השתמש בו. באיזו שגיאה תיתקל תלוי בשפת ה-SDK ובשאלה האם ה-CLI דיווח על תוצאת שגיאה לפני שיצא.

#ProcessError: Command failed with exit code

ה-SDK של Python מעלה ProcessError כאשר תהליך Claude Code יוצא עם קוד שאינו אפס:

Command failed with exit code 1 (exit code: 1)
Error output: Check stderr output for details

ההודעה מציינת את קוד היציאה פעמיים, והשורה Error output היא טקסט קבוע ולא פלט השגיאה של התהליך שלך. אותו טקסט קבוע ממלא את תכונת stderr של החריגה. תכונת exit_code של החריגה נושאת את הקוד. כדי ללכוד את מה שה-CLI כתב בפועל ל-stderr, העבר פונקציית callback של stderr בתוך ClaudeAgentOptions ותעד ביומן את מה שהיא מקבלת.

שגיאת ProcessError ללא תוספת פירושה שה-CLI יצא מבלי לדווח על תוצאת שגיאה. כאשר ה-CLI דיווח על תוצאה כזו, ה-SDK מעלה במקום זאת את ResultError, המכוסה בסעיף Claude Code returned an error result. מחלקת ResultError יורשת מ-ProcessError, ולכן except ProcessError תופס את שתיהן. כדי לטפל בהן באופן שונה, מקם את סעיף ה-except ResultError ראשון.

לפני גרסה 0.2.140 של claude-agent-sdk, ה-SDK של Python העלה יציאות עם תוצאת שגיאה כ-Exception רגיל ולא כ-ResultError.

#Claude Code process exited with code N

מעטפות IDE מדפיסות גם הן הודעה זו, וסעיף מדריך השגיאות מכסה זאת עבור VS Code ומשגרים אחרים. רשומה זו מכסה את מה שקוד ה-TypeScript SDK שלך מקבל. ה-SDK מציג יציאת CLI עם קוד שאינו אפס בתור Error רגיל שדוחה את לולאת ה-for await על הודעות query(). אין מחלקת שגיאה ייעודית של ה-SDK שניתן לתפוס, לכן עטוף את הלולאה ב-try/catch ובצע התאמה לפי תוכן ההודעה:

Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

כאשר ה-CLI כתב ל-stderr, ההודעה מסתיימת בסופו של הפלט. כדי ללכוד את הזרם המלא, העבר פונקציית callback של stderr באפשרויות השאילתה. תהליך שהופסק בעקבות אות (signal) מדווח באותו מבנה: Claude Code process terminated by signal <name>.

#Claude Code returned an error result

שני ה-SDK מחליפים את שגיאת יציאת התהליך בהודעה זו כאשר ה-CLI דיווח על תוצאת שגיאה לפני היציאה:

Claude Code returned an error result: <the CLI's own error report>

הטקסט שלאחר הנקודתיים הוא הדיווח של ה-CLI על מה שהשתבש, לכן התחל בבדיקתו ולא בעצם היציאה של התהליך. ב-Python נזרקת שגיאה מסוג ResultError, שתכונת data שלה נושאת את תוצאת השגיאה המלאה. ב-TypeScript מתקבלת דחייה של לולאת ההודעות עם Error רגיל הנושא מבנה הודעה זהה.

#פלטים מובנים

#structured_output is None but the result says success

הודעת תוצאה יכולה להסתיים עם subtype: "success" בעוד ש-structured_output הוא None ב-Python או undefined ב-TypeScript. הריצה מסתיימת, אך לא קיים פלט מאומת. דרך אחת להיתקל בכך היא סכמה שאף פלט אינו יכול לספק, לדוגמה אילוצי אורך סותרים. הריצה מסתיימת ללא שגיאת אימות, והאות היחיד לכך הוא היעדרו של structured_output.

התייחס לתוצאה זו כאל כישלון בקוד היישום. בדוק גם ש-subtype הוא success וגם ש-structured_output קיים לפני השימוש בו. סעיף טיפול בשגיאות מציג תבנית זו עבור שני ה-SDK.

אם הדבר קורה שוב ושוב עם סכמה שלדעתך נכונה, ודא שניתן לספק את דרישות הסכמה, לאחר מכן פשט אותה עד שהפלטים יעברו אימות, והחזר אילוצים אחד בכל פעם.

#דיווח על בעיה חדשה

אם השגיאה שלך אינה מכוסה כאן, בדוק את הבעיות הפתוחות או פתח בעיה חדשה במאגרי ה-SDK: claude-agent-sdk-typescript או claude-agent-sdk-python. צרף את טקסט השגיאה המלא ואת גרסת ה-SDK שלך.