Troubleshooting
Consumption
| Problem | Fix |
|---|---|
ERR_PNPM_FETCH_401 on @sumx/* | Set AZURE_ARTIFACTS_PAT in .env.local, run portal auth:azure:check, pnpm install |
Placeholder in ~/.npmrc | Replace [BASE64_ENCODED_...] with real PAT |
| Stale local kit code | pnpm run build in kit; pnpm install --force in portal |
sumx:local kit not found | Sibling clone or SUMX_KIT_ROOT in .env |
Next.js build
| Problem | Fix |
|---|---|
Route config re-export error | Define export const config = { ... } inline in pages/api/** |
Turbopack @source leaves filesystem | Only @source paths under node_modules/@sumx/* — no ../sumx-ssr-kit |
| Session dialog full-width | Ensure tailwind.css scans @sumx/ssr-auth-react and @sumx/ui |
| Problem | Fix |
|---|---|
| Chromium errors in Docker | Use portal Puppeteer/Chromium image stage |
| Timeouts | Lower HTML_TO_PDF_MAX_CONCURRENT or scale replicas |
Docs site
| Problem | Fix |
|---|---|
pnpm run docs:dev fails | Run pnpm install from repo root (workspace) |
| Port in use | Docs default port 3100 (www/package.json) |
Build: Invalid input: expected nonoptional, received undefined → at children | Zod 4.4+ breaks nextra-theme-docs Layout validation — root package.json pins pnpm.overrides.zod to 4.1.12 |