[{"data":1,"prerenderedAt":659},["ShallowReactive",2],{"navigation_en":3,"-docs-guides-troubleshooting":153,"-docs-guides-troubleshooting-surround":656},{"gettingStarted":4,"guides":41,"cli":87,"configuration":123},[5],{"title":6,"icon":7,"path":8,"stem":9,"children":10,"page":7},"Getting Started",false,"\u002Fdocs\u002Fgetting-started","docs\u002Fgetting-started",[11,16,21,26,31,36],{"title":12,"path":13,"stem":14,"icon":15},"Introduction","\u002Fdocs\u002Fgetting-started\u002Fintroduction","docs\u002Fgetting-started\u002F01.introduction","i-lucide-house",{"title":17,"path":18,"stem":19,"icon":20},"Installation","\u002Fdocs\u002Fgetting-started\u002Finstallation","docs\u002Fgetting-started\u002F02.installation","i-lucide-download",{"title":22,"path":23,"stem":24,"icon":25},"Quick Start","\u002Fdocs\u002Fgetting-started\u002Fquick-start","docs\u002Fgetting-started\u002F03.quick-start","i-lucide-zap",{"title":27,"path":28,"stem":29,"icon":30},"How It Works","\u002Fdocs\u002Fgetting-started\u002Fhow-it-works","docs\u002Fgetting-started\u002F04.how-it-works","i-lucide-workflow",{"title":32,"path":33,"stem":34,"icon":35},"Refs","\u002Fdocs\u002Fgetting-started\u002Frefs","docs\u002Fgetting-started\u002F05.refs","i-lucide-git-branch",{"title":37,"path":38,"stem":39,"icon":40},"Workspaces & Worktrees","\u002Fdocs\u002Fgetting-started\u002Fworkspaces","docs\u002Fgetting-started\u002F06.workspaces","i-lucide-folder-tree",[42],{"title":43,"icon":7,"path":44,"stem":45,"children":46,"page":7},"Guides","\u002Fdocs\u002Fguides","docs\u002Fguides",[47,52,57,62,67,72,77,82],{"title":48,"path":49,"stem":50,"icon":51},"Review a Pull Request","\u002Fdocs\u002Fguides\u002Freview-a-pull-request","docs\u002Fguides\u002F01.review-a-pull-request","i-lucide-git-pull-request",{"title":53,"path":54,"stem":55,"icon":56},"Run Dev Servers in Parallel","\u002Fdocs\u002Fguides\u002Frun-dev-servers-in-parallel","docs\u002Fguides\u002F02.run-dev-servers-in-parallel","i-lucide-plug",{"title":58,"path":59,"stem":60,"icon":61},"Seed Local Files","\u002Fdocs\u002Fguides\u002Fseed-local-files","docs\u002Fguides\u002F03.seed-local-files","i-lucide-sprout",{"title":63,"path":64,"stem":65,"icon":66},"Refresh a Workspace","\u002Fdocs\u002Fguides\u002Frefresh-a-workspace","docs\u002Fguides\u002F04.refresh-a-workspace","i-lucide-refresh-cw",{"title":68,"path":69,"stem":70,"icon":71},"Clean Up Workspaces","\u002Fdocs\u002Fguides\u002Fclean-up-workspaces","docs\u002Fguides\u002F05.clean-up-workspaces","i-lucide-trash-2",{"title":73,"path":74,"stem":75,"icon":76},"Script with uxd","\u002Fdocs\u002Fguides\u002Fscript-with-uxd","docs\u002Fguides\u002F06.script-with-uxd","i-lucide-braces",{"title":78,"path":79,"stem":80,"icon":81},"Install Shell Completions","\u002Fdocs\u002Fguides\u002Fshell-completions","docs\u002Fguides\u002F07.shell-completions","i-lucide-keyboard",{"title":83,"path":84,"stem":85,"icon":86},"Troubleshooting","\u002Fdocs\u002Fguides\u002Ftroubleshooting","docs\u002Fguides\u002F08.troubleshooting","i-lucide-stethoscope",[88],{"title":89,"icon":7,"path":90,"stem":91,"children":92,"page":7},"CLI Reference","\u002Fdocs\u002Fcli","docs\u002Fcli",[93,98,103,108,113,118],{"title":94,"path":95,"stem":96,"icon":97},"Command Grammar","\u002Fdocs\u002Fcli\u002Foverview","docs\u002Fcli\u002F01.overview","i-lucide-terminal",{"title":99,"path":100,"stem":101,"icon":102},"Workspace Verbs","\u002Fdocs\u002Fcli\u002Fworkspace-verbs","docs\u002Fcli\u002F02.workspace-verbs","i-lucide-folder-git-2",{"title":104,"path":105,"stem":106,"icon":107},"Project Verbs","\u002Fdocs\u002Fcli\u002Fproject-verbs","docs\u002Fcli\u002F03.project-verbs","i-lucide-boxes",{"title":109,"path":110,"stem":111,"icon":112},"Top-Level Verbs","\u002Fdocs\u002Fcli\u002Ftop-level-verbs","docs\u002Fcli\u002F04.top-level-verbs","i-lucide-wrench",{"title":114,"path":115,"stem":116,"icon":117},"Global Flags","\u002Fdocs\u002Fcli\u002Fglobal-flags","docs\u002Fcli\u002F05.global-flags","i-lucide-flag",{"title":119,"path":120,"stem":121,"icon":122},"Exit Codes","\u002Fdocs\u002Fcli\u002Fexit-codes","docs\u002Fcli\u002F06.exit-codes","i-lucide-circle-alert",[124],{"title":125,"icon":7,"path":126,"stem":127,"children":128,"page":7},"Configuration","\u002Fdocs\u002Fconfiguration","docs\u002Fconfiguration",[129,134,139,144,148],{"title":130,"path":131,"stem":132,"icon":133},"Overview","\u002Fdocs\u002Fconfiguration\u002Foverview","docs\u002Fconfiguration\u002F01.overview","i-lucide-settings",{"title":135,"path":136,"stem":137,"icon":138},"Project File","\u002Fdocs\u002Fconfiguration\u002Fproject-file","docs\u002Fconfiguration\u002F02.project-file","i-lucide-file-code",{"title":140,"path":141,"stem":142,"icon":143},"Commands & Hooks","\u002Fdocs\u002Fconfiguration\u002Fcommands-and-hooks","docs\u002Fconfiguration\u002F03.commands-and-hooks","i-lucide-play",{"title":145,"path":146,"stem":147,"icon":76},"Environment & Templates","\u002Fdocs\u002Fconfiguration\u002Fenvironment-and-templates","docs\u002Fconfiguration\u002F04.environment-and-templates",{"title":149,"path":150,"stem":151,"icon":152},"Editors","\u002Fdocs\u002Fconfiguration\u002Feditors","docs\u002Fconfiguration\u002F05.editors","i-lucide-app-window",{"id":154,"title":83,"body":155,"description":647,"extension":648,"links":649,"meta":650,"navigation":651,"path":84,"seo":652,"stem":85,"__hash__":655},"docs_guides\u002Fdocs\u002Fguides\u002F08.troubleshooting.md",{"type":156,"value":157,"toc":627},"minimark",[158,167,189,197,225,242,246,258,266,272,289,292,307,313,327,334,340,348,355,376,383,389,411,417,424,427,433,437,457,492,499,519,537,541,558,576,582,591,601,623],[159,160,162,163],"h2",{"id":161},"start-with-doctor","Start with ",[164,165,166],"code",{},"doctor",[168,169,174],"pre",{"className":170,"code":171,"language":172,"meta":173,"style":173},"language-bash shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","uxd doctor\n","bash","",[164,175,176],{"__ignoreMap":173},[177,178,181,185],"span",{"class":179,"line":180},"line",1,[177,182,184],{"class":183},"szw1H","uxd",[177,186,188],{"class":187},"semJd"," doctor\n",[168,190,195],{"className":191,"code":193,"language":194},[192],"language-text","OK   git version: git 2.50.1\nOK   gh (github cli): authenticated\nOK   config dir: ~\u002F.uxd\nOK   state dir: ~\u002F.local\u002Fstate\u002Fuxd\nOK   project my-project: config: schema-valid\nOK   project my-project: repo: bare repo at ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Frepo\nOK   project my-project: fetch refspec: remote.origin.fetch configured\n","text",[164,196,193],{"__ignoreMap":173},[198,199,200,201,204,205,208,209,212,213,215,216,218,219,221,222,224],"p",{},"Each line is one check, prefixed ",[164,202,203],{},"OK",", ",[164,206,207],{},"WARN",", or ",[164,210,211],{},"FAIL",". ",[164,214,203],{}," needs nothing.\n",[164,217,207],{}," is survivable — that project still works, one feature is degraded.\n",[164,220,211],{}," means something is broken, and ",[164,223,166],{}," exits non-zero if any check\nfails.",[198,226,227,229,230,233,234,237,238,241],{},[164,228,166],{}," covers: git version, ",[164,231,232],{},"gh"," presence and auth, config-dir readability,\nstate-dir writability, stale locks, and per project — schema validity, the bare\nrepo and its fetch refspec, the editor binary on ",[164,235,236],{},"PATH",", configured commands\nthat shadow built-in verbs, ",[164,239,240],{},"core.hooksPath",", and worktree\u002Fstate drift.",[159,243,245],{"id":244},"errors-by-code","Errors by code",[198,247,248,249,252,253,257],{},"Every failure prints one line to stderr, an optional ",[164,250,251],{},"hint:",", and exits with a\ncode you can branch on. See ",[254,255,256],"a",{"href":120},"Exit codes",".",[259,260,262,265],"h3",{"id":261},"e_config-exit-3",[164,263,264],{},"E_CONFIG"," — exit 3",[168,267,270],{"className":268,"code":269,"language":194},[192],"error(E_CONFIG): unknown project 'nope'\nhint: known projects: demo-app\n",[164,271,269],{"__ignoreMap":173},[198,273,274,275,278,279,281,282,285,286,257],{},"The project has no ",[164,276,277],{},"~\u002F.uxd\u002F\u003Cname>.toml",". List what ",[164,280,184],{}," can see with\n",[164,283,284],{},"uxd projects",", or create one with ",[164,287,288],{},"uxd setup",[198,290,291],{},"For a file that exists but does not parse, check it in isolation:",[168,293,295],{"className":170,"code":294,"language":172,"meta":173,"style":173},"uxd config validate\n",[164,296,297],{"__ignoreMap":173},[177,298,299,301,304],{"class":179,"line":180},[177,300,184],{"class":183},[177,302,303],{"class":187}," config",[177,305,306],{"class":187}," validate\n",[168,308,311],{"className":309,"code":310,"language":194},[192],"→ all project configs valid\n",[164,312,310],{"__ignoreMap":173},[198,314,315,318,319,322,323,326],{},[164,316,317],{},"config validate"," names the offending key and file when it fails. ",[164,320,321],{},"uxd config path"," prints which directory is actually in use — worth checking when you have\n",[164,324,325],{},"UXD_CONFIG_DIR"," set and forgot.",[259,328,330,333],{"id":329},"e_resolve-exit-4",[164,331,332],{},"E_RESOLVE"," — exit 4",[168,335,338],{"className":336,"code":337,"language":194},[192],"error(E_RESOLVE): branch 'does-not-exist' does not exist on origin\nhint: check the name, or push the ref first\n",[164,339,337],{"__ignoreMap":173},[198,341,342,344,345,347],{},[164,343,184],{}," fetched and the ref is not there. Usually a typo, or a branch that only\nexists locally in your main clone. Push it, or point at a sha instead. See\n",[254,346,32],{"href":33}," for the full resolution order.",[259,349,351,354],{"id":350},"e_git-exit-5",[164,352,353],{},"E_GIT"," — exit 5",[198,356,357,358,361,362,364,365,368,369,371,372,375],{},"A ",[164,359,360],{},"git"," or ",[164,363,232],{}," command failed. The underlying error is printed with it. Common\ncauses: no network on a first checkout (partial clones fetch lazily), a missing\n",[164,366,367],{},"remote.origin.fetch"," refspec (",[164,370,166],{}," reports it and prints the exact ",[164,373,374],{},"git config"," line to run), or authentication.",[259,377,379,382],{"id":378},"e_setup-exit-6",[164,380,381],{},"E_SETUP"," — exit 6",[198,384,357,385,388],{},[164,386,387],{},"setup"," step or a hook exited non-zero. The failing command is echoed. Fix the\ncommand, then force setup to run again on the existing workspace:",[168,390,392],{"className":170,"code":391,"language":172,"meta":173,"style":173},"uxd my-project feat\u002Flogin checkout --setup\n",[164,393,394],{"__ignoreMap":173},[177,395,396,398,401,404,407],{"class":179,"line":180},[177,397,184],{"class":183},[177,399,400],{"class":187}," my-project",[177,402,403],{"class":187}," feat\u002Flogin",[177,405,406],{"class":187}," checkout",[177,408,410],{"class":409},"ssYy9"," --setup\n",[168,412,415],{"className":413,"code":414,"language":194},[192],"→ worktree ready (reused)\n→ running setup\ninstalling deps\n",[164,416,414],{"__ignoreMap":173},[259,418,420,423],{"id":419},"e_usage-exit-2",[164,421,422],{},"E_USAGE"," — exit 2",[198,425,426],{},"Bad flags or a missing argument. The hint lists what was expected:",[168,428,431],{"className":429,"code":430,"language":194},[192],"error(E_USAGE): unsupported shell 'ksh'\nhint: one of: bash, zsh, fish\n",[164,432,430],{"__ignoreMap":173},[159,434,436],{"id":435},"common-situations","Common situations",[438,439,441,447],"note",{"title":440},"`clean` skipped a workspace",[168,442,445],{"className":443,"code":444,"language":194},[192],"warning: skipping feat-login: worktree is dirty (use --force)\n",[164,446,444],{"__ignoreMap":173},[198,448,449,450,452,453,456],{},"The worktree has uncommitted changes and ",[164,451,184],{}," will not throw them away. Commit\nor stash them, or pass ",[164,454,455],{},"--force"," if you genuinely want them gone.",[438,458,460,466,472],{"title":459},"A workspace shows `missing`",[168,461,464],{"className":462,"code":463,"language":194},[192],"SLUG        KIND    BRANCH      STATUS   PORT  AGE  LAST USED\nfeat-login  branch  feat\u002Flogin  missing  3053  2m   1m\n",[164,465,463],{"__ignoreMap":173},[198,467,468,469,471],{},"The directory was deleted outside ",[164,470,184],{},". Drop the stale state entry:",[168,473,475],{"className":170,"code":474,"language":172,"meta":173,"style":173},"uxd my-project clean --prune-state --yes\n",[164,476,477],{"__ignoreMap":173},[177,478,479,481,483,486,489],{"class":179,"line":180},[177,480,184],{"class":183},[177,482,400],{"class":187},[177,484,485],{"class":187}," clean",[177,487,488],{"class":409}," --prune-state",[177,490,491],{"class":409}," --yes\n",[438,493,495,496,498],{"title":494},"A branch is already checked out","Git allows one worktree per branch. ",[164,497,184],{}," detects this and points you at the\nexisting workspace rather than failing obscurely — use that workspace, or check\nout the sha instead of the branch name.",[438,500,502,504,505,507,508,511,512,514,515,257],{"title":501},"Hooks behave strangely (husky, `core.hooksPath`)",[164,503,166],{}," warns when ",[164,506,240],{}," is set. Relative hook paths resolve\nincorrectly from a worktree, and ",[164,509,510],{},"pnpm install"," may install hooks into the bare\nrepo. ",[164,513,184],{}," does not modify your repository — see\n",[254,516,518],{"href":517},"\u002Fdocs\u002Fgetting-started\u002Fworkspaces#known-caveats","Known caveats",[438,520,522,523,525,526,529,530,533,534,257],{"title":521},"A port is already in use","Ports are allocated deterministically from the slug, then scanned upward if the\nblock is taken. If something outside ",[164,524,184],{}," holds the port, raise ",[164,527,528],{},"base_port"," in\nthe project config or override once with ",[164,531,532],{},"--port",". See\n",[254,535,536],{"href":54},"Run dev servers in parallel",[159,538,540],{"id":539},"seeing-more","Seeing more",[198,542,543,546,547,550,551,553,554,557],{},[164,544,545],{},"-v"," \u002F ",[164,548,549],{},"--verbose"," echoes every external command ",[164,552,184],{}," runs, prefixed with ",[164,555,556],{},"· ","\non stderr:",[168,559,561],{"className":170,"code":560,"language":172,"meta":173,"style":173},"uxd my-project feat\u002Flogin checkout -v\n",[164,562,563],{"__ignoreMap":173},[177,564,565,567,569,571,573],{"class":179,"line":180},[177,566,184],{"class":183},[177,568,400],{"class":187},[177,570,403],{"class":187},[177,572,406],{"class":187},[177,574,575],{"class":409}," -v\n",[168,577,580],{"className":578,"code":579,"language":194},[192],"→ fetching origin\u002Ffeat\u002Flogin\n· git -C ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Frepo fetch origin feat\u002Flogin --no-tags\n· git -C ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Frepo worktree add ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Ftrees\u002Ffeat-login -B feat\u002Flogin --track origin\u002Ffeat\u002Flogin\n→ worktree ready: ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Ftrees\u002Ffeat-login\n",[164,581,579],{"__ignoreMap":173},[198,583,584,546,587,590],{},[164,585,586],{},"-q",[164,588,589],{},"--quiet"," does the opposite — it suppresses the step logs so only the\nresult is printed.",[198,592,593,594,596,597,600],{},"Pair ",[164,595,549],{}," with ",[164,598,599],{},"--dry-run"," to inspect a plan without executing it:",[168,602,604],{"className":170,"code":603,"language":172,"meta":173,"style":173},"uxd my-project feat\u002Flogin run dev --dry-run\n",[164,605,606],{"__ignoreMap":173},[177,607,608,610,612,614,617,620],{"class":179,"line":180},[177,609,184],{"class":183},[177,611,400],{"class":187},[177,613,403],{"class":187},[177,615,616],{"class":187}," run",[177,618,619],{"class":187}," dev",[177,621,622],{"class":409}," --dry-run\n",[624,625,626],"style",{},"html pre.shiki code .szw1H, html code.shiki .szw1H{--shiki-light:#702C00;--shiki-default:#702C00;--shiki-dark:#FFB757}html pre.shiki code .semJd, html code.shiki .semJd{--shiki-light:#032563;--shiki-default:#032563;--shiki-dark:#ADDCFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .ssYy9, html code.shiki .ssYy9{--shiki-light:#023B95;--shiki-default:#023B95;--shiki-dark:#91CBFF}",{"title":173,"searchDepth":628,"depth":628,"links":629},2,[630,632,645,646],{"id":161,"depth":628,"text":631},"Start with doctor",{"id":244,"depth":628,"text":245,"children":633},[634,637,639,641,643],{"id":261,"depth":635,"text":636},3,"E_CONFIG — exit 3",{"id":329,"depth":635,"text":638},"E_RESOLVE — exit 4",{"id":350,"depth":635,"text":640},"E_GIT — exit 5",{"id":378,"depth":635,"text":642},"E_SETUP — exit 6",{"id":419,"depth":635,"text":644},"E_USAGE — exit 2",{"id":435,"depth":628,"text":436},{"id":539,"depth":628,"text":540},"The errors uxd actually prints, what each one means, and the shortest fix — starting with uxd doctor.","md",null,{},{"icon":86},{"title":653,"description":654},"Troubleshooting uxd","Diagnose uxd problems — doctor output explained, plus fixes for E_CONFIG, E_RESOLVE, E_GIT and E_SETUP errors, missing workspaces, and dirty worktrees.","MIHau28VfVqV-rbEZg4TbvOe5hB-gfpXzl6jaZPHAs8",[657,649],{"title":78,"path":79,"stem":80,"description":658,"icon":81,"children":-1},"Generate and install tab completion for bash, zsh, or fish, so uxd completes your project names, verbs, and existing workspace slugs.",1784975262434]