📘 תיעוד 167

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

תקן שגיאות של Agent SDK כאשר ה-CLI של Claude Code נכשל בהפעלה, תהליך ה-CLI יוצא, או תוצאה מוצלחת מגיעה בלי פלט מובנה.

הדף הזה מכסה שגיאות של Agent SDK בהפעלת CLI, ביציאת תהליך CLI, ובפלטים מובנים. הרשומות בדף הזה משויכות לשגיאה שאתה רואה. כל רשומה מציינת את הסיבה ומה לעשות.

לתסמינים שקשורים ליכולת, כמו hook שלא מופעל או skill שלא בשימוש, יש סעיף פתרון תקלות בדף של אותה יכולת. הטבלה מציינת את הסעיף או הדף שמכסה כל תסמין:

#הפעלת CLI

#CLINotFoundError: Claude Code לא נמצא

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

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

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

כדי לתקן:

• התקן את Claude Code אם הוא לא מותקן. ראה התקנת Claude Code לפקודה בפלטפורמה שלך.
• אם הגדרת cli_path, ודא שהקובץ קיים ושהוא קובץ ההפעלה claude.
• אם אתה נסמך על פתרון PATH, ודא ש-claude --version עובד באותה סביבה שבה האפליקציה רצה. תהליכים שאתה מפעיל מחוץ למעטפת, כמו מ-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: סירוב להריץ סקריפט batch

ב-Windows, החיבור נכשל עם CLIConnectionError כאשר נתיב ה-CLI שה-SDK של Python משתמש בו הוא סקריפט batch מסוג .bat או .cmd, כולל ה-shim 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 מריץ סקריפטי batch על ידי שכתוב ה-spawn לקריאה cmd.exe /c, ו-cmd.exe מנתח מחדש את כל שורת הפקודה בזמן ההרצה, כך שערך של ארגומנט יכול להריץ פקודות שהוזרקו.

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

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

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

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

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

#CLIConnectionError: נכשל בהפעלת Claude Code

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

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

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

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

#CLIConnectionError: לא מחובר

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

Not connected. Call connect() first.

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

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

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

#ProcessError: הפקודה נכשלה עם קוד יציאה

ה-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 החזיר תוצאת שגיאה. ResultError יורש מ-ProcessError, ולכן except ProcessError תופס את שניהם. כדי לטפל בהם בצורה שונה, שים את פסוקית except ResultError קודם.

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

#תהליך Claude Code יצא עם קוד N

עטיפות IDE מדפיסות את ההודעה הזאת גם כן, ו-הפניית השגיאות מכסה אותה עבור VS Code ומשגרים אחרים. הרשומה הזאת מכסה את מה שקוד ה-SDK של TypeScript שלך מקבל. ה-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 באפשרויות ה-query. תהליך שנהרג על ידי signal מדווח Claude Code process terminated by signal <name> באותה צורה.

#Claude Code החזיר תוצאת שגיאה

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

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

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

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

#structured_output הוא None אבל התוצאה אומרת הצלחה

הודעת תוצאה יכולה להסתיים עם subtype: "success" בזמן ש-structured_output הוא None ב-Python או undefined ב-TypeScript. הריצה מסתיימת, אבל אין פלט מאומת.

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

• בקשה ש-Claude דחה: כדי לזהות את המקרה הזה בקוד שלך, בדוק את stop_reason בהודעת התוצאה עבור "refusal". לגבי מה לנסות בהמשך, ראה סירוב לפי מדיניות השימוש.
• סכמה שאף פלט לא יכול לספק: לדוגמה, מחרוזת ש-minLength שלה גדול מ-maxLength שלה. אם structured_output חסר שוב ושוב עם סכמה שאתה מאמין שהיא נכונה, חפש אילוצים שסותרים זה את זה. אם לא מצאת כאלה, פשט את הסכמה עד שהפלטים עוברים אימות, ואז החזר את האילוצים שלך אחד אחד.

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

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