[{"data":1,"prerenderedAt":187},["ShallowReactive",2],{"\u002Fdocs\u002Freference\u002Ftroubleshooting":3},{"id":4,"title":5,"body":6,"description":179,"extension":180,"meta":181,"navigation":182,"path":183,"seo":184,"stem":185,"__hash__":186},"docs\u002Fdocs\u002Freference\u002Ftroubleshooting.md","Troubleshooting",{"type":7,"value":8,"toc":172},"minimark",[9,13,18,28,39,47,56,60,65,68,104,112,123,128,144,149,165,169],[10,11,12],"p",{},"The issues that come up most often during setup, grouped by component.",[14,15,17],"h2",{"id":16},"caf-initiator","CAF Initiator",[10,19,20],{},[21,22,23,27],"strong",{},[24,25,26],"code",{},"caf-initiator init"," doesn't detect the stack correctly",[10,29,30,31,34,35,38],{},"Make sure the command runs from the repo's root (where ",[24,32,33],{},"package.json",", ",[24,36,37],{},"go.mod",", or\nan equivalent manifest file lives), not from a subfolder. Stack detection depends on\nmanifest files in the current working directory.",[10,40,41],{},[21,42,43,46],{},[24,44,45],{},".claude\u002Fagents\u002F"," already exists and won't regenerate",[10,48,49,50,55],{},"CAF Initiator won't overwrite existing files so it doesn't erase your customizations\n(see ",[51,52,54],"a",{"href":53},"\u002Fdocs\u002Fcore-concepts\u002Flayer-2","Layer 2: Agent Definitions","). Remove or move that\nfolder first if you actually want to regenerate it from scratch.",[14,57,59],{"id":58},"caf-orchestrator","CAF Orchestrator",[10,61,62],{},[21,63,64],{},"Webhook isn't triggering anything",[10,66,67],{},"Check, in order:",[69,70,71,83,93],"ol",{},[72,73,74,75,78,79,82],"li",{},"The webhook URL in your tracker points to the right host and path\n(",[24,76,77],{},"\u002Fwebhooks\u002Flinear"," or ",[24,80,81],{},"\u002Fwebhooks\u002Fjira",")",[72,84,85,88,89,92],{},[24,86,87],{},"WEBHOOK_SECRET"," in the Orchestrator's ",[24,90,91],{},".env"," matches exactly the secret\nregistered in the tracker",[72,94,95,96,78,100],{},"The ticket status name matches the configured mapping — see\n",[51,97,99],{"href":98},"\u002Fdocs\u002Fintegrations\u002Flinear","Linear",[51,101,103],{"href":102},"\u002Fdocs\u002Fintegrations\u002Fjira","Jira",[10,105,106],{},[21,107,108,111],{},[24,109,110],{},"\u002Fhealthz"," endpoint isn't responding",[10,113,114,115,118,119,122],{},"Check the container logs (",[24,116,117],{},"docker compose logs -f",") for startup errors — the most\ncommon cause is an incorrect ",[24,120,121],{},"REDIS_URL"," or Redis not running yet.",[10,124,125],{},[21,126,127],{},"Agent stops and escalates to a human",[10,129,130,131,135,136,139,140,143],{},"This isn't a bug — it's CAF's retry policy: a maximum of 3 attempts per phase before\nescalation (see ",[51,132,134],{"href":133},"\u002Fdocs\u002Fcore-concepts\u002Flayer-4","Layer 4: Quality Gates","). Check\n",[24,137,138],{},"verify-report.md"," in ",[24,141,142],{},".ai\u002Ftasks\u002F\u003Cticket-id>\u002F"," to see why the automated gate failed.",[10,145,146],{},[21,147,148],{},"PR doesn't open after the Implement phase finishes",[10,150,151,152,155,156,159,160,164],{},"Usually a scope issue with the Git host token. Make sure ",[24,153,154],{},"GITHUB_TOKEN","\u002F\n",[24,157,158],{},"GITLAB_TOKEN"," has write access to the repo and can open pull requests — see\n",[51,161,163],{"href":162},"\u002Fdocs\u002Fintegrations\u002Fgithub-gitlab","GitHub \u002F GitLab"," for the correct scopes.",[14,166,168],{"id":167},"still-stuck","Still stuck?",[10,170,171],{},"This page will keep growing as new issues come up. Report anything not covered here\nvia GitHub.",{"title":173,"searchDepth":174,"depth":174,"links":175},"",2,[176,177,178],{"id":16,"depth":174,"text":17},{"id":58,"depth":174,"text":59},{"id":167,"depth":174,"text":168},"Common issues when setting up CAF Initiator and CAF Orchestrator, and how to fix them.","md",{},true,"\u002Fdocs\u002Freference\u002Ftroubleshooting",{"title":5,"description":179},"docs\u002Freference\u002Ftroubleshooting","J1fKEelcsoKidiWE6dy6CBkK8juVIyR1FfhGQ27vCxY",1787621083945]