📘 תיעוד 82

איתור תקלות במוד

גלו למה מוד של Claude Code לא עושה כלום: התאימו את התסמין או ההודעה לסיבה שלהם, חפשו הודעות סירוב, וקראו את יומן הדיבוג.

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

#גלו למה מוד לא עושה כלום

כשמוד לא עושה כלום, בדקו מה Claude Code קורא מקובצי המוד, ואת השורה שהוא כותב כשהוא מדלג על משהו. עבור הראשון, ב-shell הריצו claude plugin validate עם ספריית המוד, כמו ב-claude plugin validate ./first-mod. הוא תופס אירוע עם איות שגוי, מניפסט פגום, ומודול ש-Claude Code לא יכול לקרוא, בלי להתחיל סשן.

כשמודול לא נטען, hook מדולג, או מוד אחר מסרב לשלכם, Claude Code כותב שורה אחת שמציינת את שם המוד שלכם. המקום שבו קוראים את השורה תלוי בסשן:

• סשן שעושה hot-reload לספריית פלאגין: שורה עמומה בתמליל. זה סשן אינטראקטיבי שהתחלתם עם --plugin-dir, או סשן שבו הפעלתם hot reloading למודים ש-Claude כתב.
• כל סשן אינטראקטיבי אחר, כמו סשן שמריץ מוד שהתקנתם מ-marketplace: יומן הדיבוג בלבד. כדי לקבל אחד, התחילו את הסשן עם claude --debug.
• הרצת claude -p עם --plugin-dir: stderr, בפורמט הפלט הטקסטואלי ברירת המחדל. סירוב של מוד אחר הולך ליומן הדיבוג בלבד.

#בדקו אם מודים יכולים להיטען

כדי לבדוק אם ההגדרה שלכם מאפשרת למודים להיטען בכלל, בלי להתקין אחד, הריצו claude plugin test ב-shell, מתוך ספרייה שלא מחזיקה מוד. אין צורך בסשן. ההודעה שהוא מדפיס אומרת לכם את המצב:

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

#המוד לא נטען

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

#הגרסה שלכם ישנה מדי

ראו באיזו גרסה להשתמש ואיך לבדוק את שלכם.

#שורת mods active לא מציינת את שם המוד

שום דבר שהמוד מוסיף לא מופיע, ושורת mods active ב-/plugin לא מציינת את שמו. מודול ה-hooks לא נטען. כש-Claude Code סירב לו, ביומן הדיבוג יש שורה שמתחילה ב-hooks module, שם המוד, ו-not loaded:, כמו ב-hooks module first-mod@inline not loaded: disableAllHooks in managed settings למוד שנטען עם --plugin-dir.

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

חלק מההגדרות עוצרות מוד ומשאירות את שאר הפלאגין שלו עובד. הפעלה או כיבוי של מודים מציין אותן.

#הרצת claude -p מדפיסה hooks module not loaded

השורה מתחילה בשם המוד והולכת ל-stderr. מודול ה-hooks סורב. להרצה לא אינטראקטיבית אין תמליל, ולכן ההודעה הולכת ל-stderr.

קראו את הסיבה אחרי הנקודתיים. הסעיף הודעות סירוב מפרט כל אחת.

#הודעות סירוב

כל אחת מאלה באה אחרי hooks module, שם המוד, ו-not loaded: ביומן הדיבוג.

#הודעות מהשומר המובנה

במכונה עם הגדרות מנוהלות, או בסשן שפרטי ההזדהות שלו הם /login של Team או Enterprise, השומר המובנה יכול לסרב למוד או לאחת מהתשובות שלו. כל הודעה מציינת את האפשרות שמנהל הארגון שלכם מגדיר כדי לשנות את הכלל.

#validate עובר ולא מציג שורת hooks

ל-hooks/hooks.json אין מפתח modules, או שהמפתח באיות שגוי.

הוסיפו "modules": ["./register.js"].

#hooks module did not load

השורה מתחילה בשם המוד, ואז hooks module did not load: וסיבה, שמציינת את הקובץ והשורה כשהבעיה בקוד שלכם. Claude Code לא הצליח לטעון את המודול, למשל כי הקוד ברמה העליונה זרק.

תקנו את השגיאה שהסיבה מציינת.

אם הסיבה מסתיימת ב-; the version loaded before is unloaded, אף גרסה של המוד לא רצה עכשיו. אחרי שתתקנו את השגיאה, הריצו /reload-plugins בסשן כדי לטעון את המוד שוב. אם התקנתם את המוד ולא כתבתם אותו, בקשו מהמחבר לתקן את השגיאה.

#options do not fit plugin.json userConfig

השורה מתחילה בשם המוד, ואז hooks module did not load: options do not fit plugin.json userConfig: וסיבה. אפשרות נכשלת באימות מול שדה userConfig שלה, למשל מספר מעל max של השדה, או שלשדה חובה אין ערך.

הגדירו או שנו את הערך. סוף השורה מציין את רשומת pluginConfigs שלו ב-settings.json.

#code nested too deep to scan: more than 2000 scopes

השורה מתחילה בשם המוד, ואז hooks module did not load:, הקובץ, ו-code nested too deep to scan: more than 2000 scopes. קובץ במודול hooks לא יכול לקנן scopes, כמו פונקציות, בלוקים ולולאות, ביותר מ-2,000 עומק. claude plugin validate מדווח על אותה סיבה.

כתבו מחדש את הקוד כך שה-scopes שלו יקוננו פחות עמוק.

#the engine ran out of stack linking the file and its imports

קוד במודול ה-hooks מקונן עמוק מדי, או ששרשרת ה-imports שלו ארוכה מדי, מכדי ש-Claude Code יטען אותו. השורה מתחילה בשם המוד וב-hooks module did not load:, ואז נותנת שם של קובץ ואת הסיבה הזו.

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

#the parser stopped או the engine ran out of stack loading the file

קוד בקובץ אחד של מודול ה-hooks מקונן כל כך עמוק ש-Claude Code נגמר לו ה-stack בזמן הקריאה שלו. השורה מתחילה בשם המוד וב-hooks module did not load:, ואז נותנת את שם הקובץ הזה ואחת מהסיבות האלה:

• code nested too deep to scan (the parser stopped: <message>)
• the engine ran out of stack loading the file (code nested too deep): <message>

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

#אף מוד לא נטען בספרייה שפתחתם בפעם הראשונה

עוד לא עניתם להנחיית האמון של הספרייה.

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

#אף פלאגין מותקן לא נטען בכלל

התחלתם את Claude Code עם --safe-mode.

התחילו בלי הדגל.

#Claude Code מפסיק לשאול אם להפעיל hot reloading

Claude כותב מוד בסשן אינטראקטיבי, שום דבר לא נטען, ו-Claude Code לא שואל שוב אם להפעיל hot reloading. אם השאלה מסתיימת שלוש פעמים בלי שנבחרה תשובה, hot reloading נשאר כבוי. למשל, השאלה מסתיימת כך כשאתם מגדירים askUserQuestionTimeout והזמן עובר לפני שאתם עונים. ההגדרה הזו חלה כאן כי Claude Code שואל באותה תיבת שאלה ש-AskUserQuestion משתמש בה. שאלה שאתם דוחים בעצמכם לא נספרת לשלוש.

כדי להריץ את המוד, העתיקו את הספרייה שלו אל מחוץ לתיקיית המודים, ואז ב-shell התחילו סשן חדש עם --plugin-dir, כמו ב-claude --plugin-dir ~/mods/git-branch.

#hook מדולג או מוד נפרק

המוד נטען, ואז Claude Code דילג על אחד מה-hooks שלו או פרק אותו.

#hook skipped

השורה מציינת את המוד ואת האירוע, ואז אומרת hook skipped: וסיבה, כמו ב-first-mod: tool.call hook skipped: threw Error: boom. hook זרק, חרג ממגבלת הזמן שלו, או החזיר תוצאה בצורה לא נכונה. השורה מופיעה פעם אחת לכל אירוע וסוג כשל עד שהמוד נטען מחדש.

תקנו את השגיאה. ביומן הדיבוג יש שורה לכל מופע.

#no command.run hook answered it

אתם מריצים פקודה שהמוד שלכם הוסיף, והתשובה מציינת את המוד ואת הפקודה, כמו ב-first-mod registered /tally but no command.run hook answered it, ואז אומרת לכם להוסיף hook. Claude Code מדפיס את התשובה הזו כשהפקודה מגיעה לסוף השרשרת בלי תשובה, וזה קורה בשני מקרים:

• אף hook לא ענה לפקודה: למודול אין hook מסוג command.run, ה-filter של ה-hook מציין פקודה אחרת, או שה-hook החזיר next(e)
• Claude Code דילג על ה-hook: hook skipped מפרט את הסיבות. העברת focus: false ל-$.ui.open היא אחת הדרכים להגיע לשם.

אם למודול כבר יש את ה-hook שהתשובה מתארת, חפשו שורת hook skipped שמציינת command.run, והיא נותנת את הסיבה. בדיקה שמריצה את הפקודה נכשלת מאותה סיבה.

#it crashed the hooks worker

השורה מתחילה בשם המוד, כמו ב-first-mod was unloaded: it crashed the hooks worker. מודים מותקנים חולקים thread אחד של worker. ה-worker הפסיק להגיב או קרס, ו-Claude Code ייחס את זה למוד הזה ופרק אותו. hook שחוסם את ה-thread, כמו לולאה שלעולם לא עושה await, הוא סיבה אחת.

תקנו את ה-hook.

#its session.start ran again in a fresh copy

השורה מתחילה בשם המוד ומציינת קריאה ל-$.prompt.submit, $.command.run, או $.agent.spawn, כמו ב-first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again. Claude Code טען שוב את המודול של המוד, למשל אחרי ש-hooks worker קרס והוחלף, ו-hook session.start של העותק החדש רץ. הקריאה שהשורה מציינת נפתרה עם תוצאת ההרצה הראשונה שלה במקום לרוץ שוב, כך שהמוד שלכם לא שולח את ה-prompt, לא מריץ את הפקודה, ולא מתחיל את ה-subagent פעמיים. שאר ה-hook רץ כרגיל.

אין מה לתקן.

לפני v2.1.292, הקריאה רצה פעם שנייה, כך שה-prompt נשלח, הפקודה רצה, או ה-subagent התחיל פעמיים.

#This mod's change didn't load או the earlier version is no longer running

שינוי במוד ש-Claude כתב בסשן הזה לא הצליח להיטען. שורת התמליל מתחילה בשם המוד ומסתיימת בסיבה:

• This mod's change didn't load, so the earlier version is still running: <reason>.
• This mod didn't load, and the earlier version is no longer running: <reason>.

Claude לא רואה את השורה הזו, אז הדביקו אותה בהודעה הבאה שלכם כשאתם מבקשים מ-Claude תיקון.

#$.agent.register refused: the hooks module that made the call is no longer loaded

השורה מתחילה בשם המוד שלכם, כמו ב-first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), וה-agent לא רשום. המוד שלכם נטען מחדש או נפרק לפני הקריאה. טעינה מחדש טוענת עותק חדש של מודול ה-hooks, והקריאה הזו הגיעה מקוד שעדיין רץ בעותק הישן, כמו hook שעדיין לא חזר.

אם ה-hook הזה לא תופס את ה-rejection, הוא נכשל ו-Claude Code מדלג עליו. כדי לרשום את ה-agent מהעותק שנשאר טעון, בצעו את הקריאה ב-hook session.start שלכם, שרץ שוב בכל עותק חדש אחרי טעינה מחדש.

#mods that run in the hooks worker are off for this session

השורה היא hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. ה-worker נעצר שלוש פעמים ו-Claude Code לא הצליח לייחס את העצירות למוד אחד, אז הוא פרק כל מוד שאינו מובנה, כולל מודים שהארגון שלכם מתקין. השורה הזו מגיעה לתמליל בכל סשן אינטראקטיבי.

הריצו /reload-plugins כדי לטעון אותם שוב.

#קריאת כלי נדחית

המוד נטען וה-hooks שלו רצים, וקריאת כלי שהוא נגע בה נדחית.

#a hook changed this call's input after the model wrote it

במצב auto, קריאת כלי שנדחתה נותנת את הסיבה הזו. hook שינה את הקלט של קריאת הכלי אחרי שהמסווג בצד השרת סקר אותה, כך שהסקירה הזו לא מכסה את מה שהיה רץ. ה-hook יכול להיות hook tool.call או turn.step של מוד, או hook הגדרות PreToolUse. ההודעה לא אומרת איזה.

ההודעה אומרת ל-Claude להוציא את הקריאה עוד פעם אחת כפי שנרשמה. אם גם זו נדחית, ה-hook משנה את הקלט בכל פעם, אז כבו את המוד או ה-hook, או צאו ממצב auto ואשרו את הקריאה בעצמכם.

[!NOTE]

בחלק מסשני טרמינל אינטראקטיביים וסשני VS Code, אותה דחייה נותנת את הסיבה a hook changed this call's input after auto mode reviewed it. הקריאה החוזרת שם נושאת את השינוי הראשון של המוד, ו-hook tool.call עדיין רץ עליה, אבל שינוי נוסף נזרק. אין צורך לשנות את המוד שלכם אלא אם Claude אומר לכם בתשובה שלו שמצב auto לא הצליח לבדוק את הקריאה.

#הודעה על כללי ה-deny בהגדרות שלכם

tried to lift a deny rule in your settings ו-the deny rules in your settings could not be checked for this call, so it is refused שניהם מגיעים מהשומר המובנה.

חפשו אותם בהודעות מהשומר המובנה.

#מופיעה הודעת toast אחרי שתור נעצר

#Stopped: type a message to continue; a mod cannot resume work after Stop

הודעת toast זו אומרת שאחרי שעצרת את התור, למשל עם Esc, מוד ניסה להתחיל עבודה בעצמו ו-Claude Code לא אפשר לו. אין מה לתקן. אחרי ההודעה הבאה שלך, מודים יכולים להתחיל עבודה שוב וחלק מהעבודה הזו חוזר מעצמו. אם מה שציפית מהמוד לא חוזר, בקש אותו שוב או הרץ שוב את הפקודה של המוד.

אם כתבת את המוד, ראה קריאות ועבודת רקע אחרי שהמשתמש קוטע תור.

#ציור לא מופיע או לא מגיב

המוד נטען, והחלונית, הפס, הודעת ה-toast או הפקדים שלו לא מתנהגים כפי שאתה מצפה.

#הפס של מוד אחר מופיע והפס שלך לא

יש פס אחד מעל שורת ההנחיה, וכל המודים חולקים אותו. מוד שרץ לפני שלך מחליף את הפס שלך כשהוא מחזיר עץ בלי התוצאה של next(e) בתוכו. כדי להציג את שני הפסים, שנה את ה-hook של המוד הזה, או בקש מהמחבר שלו:

• לשמור את הפסים שאחריו: שים את התוצאה של await next(e) בין הילדים של Box בעץ שלו, כמו בלשונית Band above the prompt של בחר איפה לצייר
• לשמור על העץ תקין: אל תיתן ל-Box הזה, או ל-Box כלשהו סביבו, prop של width, height, minWidth, minHeight, position, top, left, right, bottom, display או overflow

כדי למצוא את המוד הזה, כתוב יומן ניפוי וחפש בו answered ui.render without next(). שורה כמו other-mod (user) answered ui.render without next() מציינת מוד שהחזיר את העץ שלו בלי לקרוא ל-next(e). היא לא מציינת את אתר הרינדור, כך שגם מוד של חלונית בלבד יכול להופיע. מוד שקורא ל-next(e) ומשמיט את התוצאה לא מקבל שורה, אז בדוק גם את ה-hooks שלפני שלך.

הפס של מוד חסר גם כשהעץ שה-hook שלו עצמו החזיר לא עובר אימות, והפסים של המודים האחרים נשארים. כדי למצוא איזה מוד ולמה, כתוב יומן ניפוי וחפש בו ui.render hook skipped.

#חלונית או פס ריקים או מציגים את התוכן הרגיל של Claude Code

העץ שה-hook שלך החזיר לא עבר אימות. שורת hook skipped בתמליל או ביומן הניפוי מציינת את המוד שלך ואת הסיבה, כמו זו עבור Box בחלונית:

first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

תקן את מה שהסיבה מציינת. אם הסיבה נחתכה, כתוב יומן ניפוי וחפש בו a hook returned a tree that does not validate כדי לקרוא את השאר.

אם השורה אומרת במקום זאת refused: מיד אחרי שם האתר, כמו ב-ui.render (Pane) refused:, ראה שורת ui.render אומרת refused.

#שורת ui.render אומרת refused

ui.render (<site>) refused:, או ui.render (<site>): the chain settled on a tree that does not validate ביומן הניפוי, פירושו שהעץ באתר הזה חורג ממגבלת גודל. כל אחת מהשורות מציינת את אתר הרינדור ואז את הסיבה, והסיבה מציינת את המגבלה.

שנה את המודים שמציירים באתר הזה כך שה-hooks של ui.render שלהם יחזירו עצים קטנים יותר, או בקש מהמחברים שלהם. אם שורת התמליל מתחילה ב-hooks, ליותר ממוד טעון אחד יש hook של ui.render לאתר הזה, אז בדוק את העץ של כל אחד מהמודים האלה. עבור כמה מודים שהפסים שלהם מעל שורת ההנחיה מקוננים לעץ בעומק של יותר מ-32 רמות, השורה נקראת:

hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

לפני v2.1.307, שורת refused: לכל אתר דיווחה על כל עץ שלא עבר אימות, ועבור Pane ו-AbovePrompt היא הסתיימה ב-; the engine drew its own. בגרסאות האלה, תקן את מה שהסיבה מציינת.

#needs a key, is drawn twice, או key each once

לאלמנט בעץ שה-hook של ui.render שלך מחזיר אין key תקין, או ששני אלמנטים חולקים אחד. מצא את ההודעה שקיבלת:

• <Input> needs a key או <Select> needs a key: לאלמנט אין prop של key, או שה-key שלו ריק או שאינו מחרוזת, כמו ב-key: 3. תן לו מחרוזת לא ריקה בתור ה-key שלו.
• <Button> needs a key: תן לכפתור מחרוזת לא ריקה בתור ה-key שלו
• is drawn twice; each takes its own key: לשני אלמנטים מהסוג שההודעה מציינת יש אותו key, כמו ב-Input "size" is drawn twice; each takes its own key. תן לכל אלמנט key משלו.
• key each once מ-press בבדיקה: בציור יש יותר מכפתור אחד עם ה-key שהעברת. כפתורים עם אותה תווית ובלי prop של key חולקים את התווית הזו בתור ה-key שלהם. תן לכל כפתור key משלו.

#שורת ui.render אומרת threw while drawn

השורה מציינת את אתר הרינדור, ואז אומרת threw while drawn: ואת השגיאה, כמו ב-first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code נתקל בשגיאה הזו בזמן ציור העץ שה-hook של ui.render שלך החזיר, או בזמן ציור האתר מתוך ה-props שה-hook שלך העביר ל-next. הסיום the engine drew its own אומר שהאתר מציג את התוכן הרגיל של Claude Code.

קרא את השגיאה ותקן את הערך ב-hook שלך שגרם לה.

לפני v2.1.289, השגיאה הזו בשורת תמליל סיימה את הסשן עם Claude Code exited after an unrecoverable interface error.

#the module failed without a message

Client נכשל עם שגיאה שאין לה הודעה, כמו throw new Error(). השורה במקומה נקראת כמו my-mod: Client client/spinner.js: the module failed without a message.

מצא את ה-throw בקוד של ה-Client שלך ותן לשגיאה הודעה. השורה אז מציגה את ההודעה הזו.

לפני v2.1.289, השורה הציגה Error בתור הסיבה במקום.

#$.ui.open רץ ולא מופיעה חלונית

הקריאה לא הגיעה ממשהו שהמשתמש עשה, והטרמינל צר יותר מהרוחב שהחלונית צריכה.

פתח את החלונית מפקודה או מכפתור, או בדוק את תוצאת isPlaced של הקריאה. ראה פתח חלונית בזמן הנכון.

#הודעת toast לא מופיעה

המוד שלך קורא ל-$.ui.toast בסשן טרמינל אינטראקטיבי ואתה לא רואה את הודעת ה-toast. כדי לאשר שהקריאה רצה, חפש ביומן הניפוי שורה עם שם המוד שלך והטקסט של הודעת ה-toast, כמו ב-$.ui.toast (first-mod): build finished. אחר כך בדוק סיבות כמו אלה:

• השורה של הקריאה חסרה: חפש שורה שאומרת למה Claude Code סירב לקריאה, כמו ב-first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• חלונית מחזיקה הודעות toast: המוד שלך או מוד אחר העביר holdToasts כשפתח את החלונית שמוצגת. סגור את החלונית כדי לסיים את ההחזקה. אם החלונית שלך ונועדה להישאר פתוחה, הסר את holdToasts מקריאת $.ui.open שלה ופתח את החלונית שוב.
• הודעת ה-toast מתחת לשורת ההנחיה: במרנדר הקלאסי, הסתכל מימין מתחת לשורת ההנחיה. הודעת toast שם היא שורה אחת שמתחילה בשם המוד, במקום תיבה בפינה הימנית העליונה.
• המוד שלך העלה הודעת toast חדשה יותר: במרנדר הקלאסי, הודעת toast חדשה יותר מהמוד שלך יכולה לתפוס את המקום של אחת שמוצגת או ממתינה להצגה. ביומן הניפוי יש שורה נוספת להודעת ה-toast הישנה יותר, שמסתיימת ב-gave way, cut short כשהיא הוצגה, או ב-gave way, unseen כשהיא לא הופיעה מעולם. כדי להציג את שתי ההודעות, שים אותן בהודעת toast אחת.
• הודעת ה-toast נגמר לה הזמן בלי שצוירה: ברינדור מסך מלא, Claude Code מצייר לכל היותר שלוש הודעות toast בבת אחת, כך שהודעת toast יכולה שייגמר לה הזמן לפני שהיא מצוירת. ביומן הניפוי יש שורה נוספת להודעת toast זו, שמסתיימת ב-left the stack, never drawn. כשהמוד שלך מעלה כמה בבת אחת, שים את ההודעות בהודעת toast אחת.

לפני v2.1.290, Claude Code זרק הודעת toast שהועלתה בתוך שתי שניות מהאחרונה שהציג עבור המוד שלך, ושורת יומן הניפוי של הודעת ה-toast שנזרקה אמרה within 2000ms of the last; dropped.

#הפס מציג plugin panel hidden

הפס מכווץ. הוא מתכווץ כשאתה לוחץ Ctrl+X ואז Ctrl+A, או את המקשים שקשרת במקומם, וברינדור מסך מלא כשאתה לוחץ על [-] בשורה הראשונה שלו. הוא נשאר מכווץ עד שאתה מרחיב אותו או מפעיל את Claude Code שוב, ובינתיים שום קיצור מקלדת או קישור action לא לוחץ על כפתור בתוכו.

כדי להרחיב את הפס, לחץ על המקשים שהשורה מציינת, Ctrl+X ואז Ctrl+A כברירת מחדל, או ברינדור מסך מלא לחץ על השורה.

#קיצורי מקלדת לא עושים כלום

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

• אין מיקוד מקלדת: לחץ Ctrl+X ואז Tab או, ברינדור מסך מלא, לחץ על החלונית או על הפס. כדי שהחלונית תקבל מיקוד כשהיא נפתחת, פתח אותה עם focus: true מפקודה.
• הכפתור נמצא בפס מכווץ: הפס מציג שורה עמומה אחת שמתחילה ב-▸ plugin panel hidden. לחץ על המקשים שהשורה מציינת, Ctrl+X ואז Ctrl+A כברירת מחדל, כדי להרחיב אותו.
• בהרחבה של VS Code: לחץ על הכפתור, או לחץ Enter עליו אחרי שיש לו מיקוד

#ציור עובד בטרמינל ולא באפליקציית Desktop או ב-VS Code

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

• האתר או האלמנט לא מצויר באפליקציה הזו: חפש את האתר שלך בטבלת אתרי הרינדור ואת האלמנטים שלך בטבלת האלמנטים. עבור אלמנט שהאפליקציה חסרה, בדוק את e.surface ב-hook והחזר עץ שהאפליקציה יכולה לצייר.
• הרחבת VS Code ישנה מ-2.1.299: לוח הצ'אט מצייר עבור מודים מגרסת ההרחבה 2.1.299. בדוק את הגרסה בתצוגת Extensions של VS Code ועדכן את ההרחבה שם.
• ההרחבה ישנה מ-2.1.304 והסשן לא מביא feature flags: עדכן את ההרחבה, או הרץ claude בטרמינל המשולב של VS Code במקום. סשנים ב-Amazon Bedrock, ב-Agent Platform של Google Cloud, או ב-Microsoft Foundry מדלגים על ההבאה. עבור האחרים שמדלגים על זה, כמו סשן של Claude apps gateway, ראה יכולות שצריכות הבאת feature flags.

#עריכה או ערך אבדו

המוד רץ, ושינוי שעשית או ערך שהוא שמר אינם שם.

#העריכות שלך לא נכנסות לתוקף

אתה עורך תוסף שהתקנת. Claude Code מריץ את העותק שבמטמון של הגרסה המותקנת.

פתח בפיתוח עם --plugin-dir שמצביע על עותק העבודה שלך, כמו ב-claude --plugin-dir ./first-mod, שנטען מחדש כשאתה שומר.

#ערך מתאפס כשהמודול נטען מחדש

משתנים ברמת המודול מאותחלים מחדש בכל טעינה מחדש.

שמור את הערך ב-$.state או ב-$.store.

#ערך מתאפס אחרי /clear, /resume או /branch

ערך מתאפס, או שערך שנשמר מוחלף בברירת המחדל שלו. כל אחת מהפקודות האלה מאפסת את $.state לברירות המחדל שלו, ו-session.start לא מופעל שוב.

טען שוב את הערך שנשמר ב-hook של classic.SessionStart.

#מפתח ש-hook ה-settings.read שלך מחזיר לא נכנס לתוקף

אם אתה מחזיר כללי הרשאה או env בקריאה העצמית של Claude Code, הכללים לא נבדקים בקריאות לכלים, ורשומות env לא הופכות למשתני סביבה. השתמש בקובץ הגדרות לשניהם, או ב-$.env.set עבור env.

עבור מפתח אחר, בדוק אילו מודים מקבלים settings.read ומאיזו גרסה, ואז חפש ביומן הניפוי את settings.read וחפש אחת מהשורות האלה:

אם אף שורה לא מסבירה את המפתח, בדוק במודים שרצים לפני שלך אם יש hook של settings.read שמשנה את המפתח. כבה את המוד הזה, או בקש ממנהל הארגון שלך. אם אף hook לא עושה זאת, הגדר את המפתח בקובץ הגדרות.

#the answer for <key> is no value the key can hold

שורת יומן הניפוי הזו אומרת ש-Claude Code סירב לערך ש-hook של settings.read החזיר עבור המפתח ששמו מופיע, ורק עבור המפתח הזה:

settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

הערך שהוחזר עבור המפתח ששמו מופיע לא התאים לסכמה של המפתח הזה, למשל לפי סוג או לפי טווח.

• הערך שלך לא מתאים לסכמה של המפתח: החזר ערך שרשומת הפניית ההגדרות של המפתח מתירה.
• הערך שלך מתאים: הערך שלא מתאים הגיע מ-hook של settings.read של מוד אחר. כדי למצוא את המוד הזה, פעל לפי השלבים לכיבוי מודים אחד בכל פעם. חפש בכל יומן חדש את השורה הזו במקום refused to the engine.

כל עוד הערך לא מתאים, המפתח שומר על הערך שמוזג ממקורות ההגדרות לפני ש-hook כלשהו ענה. השורה קוראת לזה הערך העצמי של ההגדרות.

#settings.read: refused to the engine

אתה רואה את השורה הזו ביומן הניפוי כשהקריאה העצמית של Claude Code מסורבת, ו-Claude Code משמיט את הערך של כל hook. כש-hook של settings.read מסרב לקריאה הזו עם { deny: reason }, השורה נושאת את הסיבה של ה-hook הזה:

settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

חפש בקוד שלך את הסיבה שבסוגריים:

• הקוד שלך מכיל אותה: ה-hook שלך סירב לקריאה. גרום לו להחזיר { value } כש-next.origin מראה את הקריאה העצמית של Claude Code.
• הקוד שלך לא מכיל אותה: כבה את שאר המודים שלך אחד בכל פעם. אם הארגון שלך פרס מוד, בקש מהמנהל שלו לכבות אותו. אחרי כל אחד:
  1. הפעל את הסשן מהמעטפת שלך עם claude --debug-file ./settings-read-2.log, ואחריו הדגלים שאיתם הוא הופעל. השתמש בנתיב חדש בכל פעם.
  2. חפש בקובץ הזה את refused to the engine. אם השורה שם, כבה את המוד הבא. אם לא, המוד האחרון שכיבית סירב לקריאה, אז השאר אותו כבוי.

אם השורה נשארת כשלא נשאר מוד אחר, הגדר את המפתחות שה-hook שלך מחזיר בקובץ הגדרות. הערכים שלו נשארים בתוקף כל עוד הקריאה מסורבת.

#קרא את יומן הניפוי

ליומן הניפוי יש שורה עבור כל מודול ש-Claude Code טוען או מסרב לו, כל hook שנכשל, וכל תוצאה שהוא מסרב לה, ולכן זה המקום לחפש כשהתמליל לא מראה כלום. כדי לכתוב אחד, במעטפת שלך הפעל את Claude Code עם --debug, או עם --debug-file <path> כדי לבחור לאן הוא נכתב:

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

במסוף אחר, עקוב אחרי הקובץ וסנן לפי שם המוד שלך:

tail -f ./mod-debug.log | grep first-mod

למוד שנטען יש שורה שמציינת אותו ומפרטת את האירועים שהוא מטפל בהם. מוד שנטען עם --plugin-dir מופיע תחת השם שלו ואחריו @inline:

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

כדי לכתוב שורות משלך ביומן, קרא ל-$.ui.log עם ארגומנט שני, כמו ב-$.ui.log('message', { to: 'debug' }). בלי הארגומנט השני, $.ui.log מוסיף שורה עמומה לתמליל.

בזמן שאתה עורך מוד שנטען עם --plugin-dir, התמליל מראה שורה עבור כל טעינה מחדש שמציינת את המוד ומפרטת את ה-hooks שלו. אם שמירה שוברת את המודול, השורה אומרת reload failed, the previous version stays loaded: עם הסיבה, והגרסה העובדת האחרונה ממשיכה לרוץ עד ש-Claude Code טוען מחדש תוספים בפעם הבאה, למשל כשאתה מריץ /reload-plugins.

#הצעדים הבאים

• בדוק מוד: אתר בעיות לפני שהן מגיעות לסשן
• פתור תקלות בתוספים: בעיות בהתקנה ובטעינה של תוסף שאינן ספציפיות למודים