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