Troubleshooting

title: Troubleshooting

description: Checklist when install, boot, or module development fails. navigation: icon: i-lucide-circle-help

Nx: ENOENT playground/.nuxt/tsconfig.json

Symptom: pnpm run dev fails with Failed to process project graph and @nx/js/typescript cannot open …/playground/.nuxt/tsconfig.json.

Cause: Module/theme playgrounds extend ./.nuxt/tsconfig.json, which exists only after nuxt prepare (dev:prepare). Root postinstall runs prepare:stubs only, not every playground.

Fix (desktop dev): The client nx.json excludes **/playground/** from the TypeScript plugin — run nx reset after pulling that change.

Fix (work on a module playground):

pnpm --filter @owdproject/module-fs run dev:prepare
# or: pnpm run prepare:modules
nx reset

Then pnpm run dev (desktop) or the package’s own pnpm run dev.

desktop.config.ts not found

• The file must live in the same root Nuxt uses as **rootDir** (usually **desktop/**).
• Legacy name **owd.config.ts** still works — prefer renaming to **desktop.config.ts**.
• Fix syntax errors: core throws with path and remediation text.

ERR_PNPM_WORKSPACE_PKG_NOT_FOUND

Cause: **package.json** declares **"some-pkg": "workspace:*"** but that package is not in the pnpm workspace (no folder under packages/*, themes/*, etc.).

Common case: **@owdproject/module-fs** or **@owdproject/module-persistence** with **workspace:*** after those modules were removed from the client monorepo.

Fix:

1. Replace with npm semver: **"@owdproject/module-fs": "^3.4.0"**, or
2. Run **desktop add module-fs --dev** to clone into the workspace, or
3. Remove the dependency if the feature is optional.

Full guide: Package linking.

App missing from launcher

• Listed under **desktop.config.ts** → apps**`?
• Dependency in **desktop/package.json** and **pnpm install** run?
• For packages with **dist/**, run **pnpm run dev:prepare** or **prepare:stubs**?

Explorer / filesystem does nothing

• Is **@owdproject/module-fs** in **desktop.config.ts** → modules**`?
• Does the theme install **@owdproject/kit-primevue** when filesystem features are needed?
• Explorer UI state lives in **@owdproject/module-fs** (useExplorerStore), and UI components live in **@owdproject/kit-primevue**.

Tailwind classes not applied in a module

• Call **registerTailwindPath** (imported from **@owdproject/kit-tailwind/kit/registerTailwindPath**) in **module.ts** with globs covering your **.vue** files.
• Restart the dev server after adding paths.

defuOverride or dialog import errors

• **defu** v6 exports **defu** only — use **defu(newConfig, existing)** for overrides (left wins).
• Dialog contract is handled by **@owdproject/kit-primevue**: **useDesktopDialogs**, **DESKTOP_DIALOG_PROVIDER_KEY**. Themes install **kit-primevue** which registers the provider.

Two Git repos on one folder

• Nested **.git** under **themes/my-theme** is expected when using gitignored clones. Pick one workflow: monorepo workspace clone, standalone repo + npm peers, or git URL dependency — see Package linking.

Version skew

• Align **peerDependencies** on **@owdproject/core** (^3.4.0 with current kernel). Mismatches surface as missing exports (**CoreDesktop** renamed to **DesktopCore** in 3.3) or store moves (**useDesktopExplorerStore** → **useExplorerStore** in **@owdproject/module-fs**).
• Run **desktop validate .** in theme/app repos before publish.

prepare:stubs filters missing packages

• Root **prepare:stubs** targets **extend/packages/***, **apps/***, **themes/***. If a script still references removed paths, update **package.json** scripts at the repo root.