# Troubleshooting cascivo
The failures adopters actually hit, in FAQ form. Each entry: symptom → cause →
fix.
---
## `pnpm lint` errors on every signal write: `Error: This value cannot be modified`
```
error Error: This value cannot be modified
Modifying a value returned from a hook is not allowed.
onValueChange={(v) => (env.value = v)}
^^^ `env` cannot be modified
```
Also seen as `react-hooks/immutability`, as oxlint's
`warning react(immutability): This value cannot be modified`, and on
`open.value = !open.value`, `count.value++`, or any other `signal.value = …`
assignment.
**Cause:** `eslint-plugin-react-hooks@7` enables `react-hooks/immutability` in
`recommended-latest` — the config a stock 2026 React app gets — and **oxlint**
ports the same rule as `react/immutability`, which is what
`pnpm create vite --template react-ts` scaffolds. The rule reports writes to
values returned from hooks, and `useSignal()` / `useSignalState()` return one. Assigning
`.value` works at runtime — older cascivo docs taught it — but the rule flags it, and the React
Compiler refuses to compile it.
**Fix without turning anything off:** write through a setter instead of assigning. The
setter form passes this rule _and_ compiles under the React Compiler (checked in CI):
```tsx
const [open, setOpen] = useSignalState(false)
// read open.value in render; in handlers call setOpen(next) instead of open.value = next
```
**Or turn the rule off — ESLint:**
```sh
pnpm add -D --save-exact @cascivo/eslint-config
```
```js
// eslint.config.js
import cascivo from '@cascivo/eslint-config'
export default [...yourConfig, ...cascivo] // spread LAST
```
Or set it directly: `{ rules: { 'react-hooks/immutability': 'off' } }`.
**Or turn the rule off — oxlint** (no `eslint.config.js` to spread into):
```jsonc
// .oxlintrc.json
{ "extends": ["./node_modules/@cascivo/eslint-config/src/oxlintrc.json"] }
```
Or set it directly: `{ "rules": { "react/immutability": "off" } }`.
**Not** fixable by scoping the rule to `src/components/ui/**` — signal writes are
in your own pages, and on the prebuilt path that directory doesn't exist.
See [USING-WITH-STRICT-ESLINT.md](/docs/using-with-strict-eslint.md) §1 for why the
rule cannot be narrowed, what turning it off costs, and cascivo's React Compiler
position.
---
## Components render unstyled (no colors, wrong font, no padding)
**Cause:** the themes CSS is not loaded. Component CSS only defines structure —
it references `var(--cascivo-*)` custom properties that do not exist until
`@cascivo/tokens` + a theme are loaded, so alone it yields correctly-structured
but uncolored components.
**Fix:** import the themes once in your entry file (or Next.js root layout) and
set `data-theme`:
```tsx
import '@cascivo/themes/light-dark.css' // tokens (once) + base typography + light & dark
```
```tsx
…
```
See [GETTING-STARTED.md](/docs/getting-started.md#the-critical-wiring-themes--data-theme).
---
## `tsc` fails on the CSS import: `Cannot find module '@cascivo/react/styles.css'` (TS2307 / TS2882)
**Symptom:** the app runs and is styled, but a typecheck step (`tsc --noEmit`) reports
`TS2307: Cannot find module '@cascivo/react/styles.css' or its corresponding type
declarations` on the CSS import (also `@cascivo/themes/all.css`, `@cascivo/charts/styles.css`).
On a strict scaffold with `noUncheckedSideEffectImports` (e.g. TanStack Start) the same import
reports `TS2882` instead.
**Cause:** a bare CSS **side-effect import** has no TypeScript types on its own. Vite ships
ambient `*.css` module declarations via `vite/client`, but a project whose `tsconfig` doesn't
reference them — or one that opts into `noUncheckedSideEffectImports` — doesn't see them. This
is a standard Vite/TypeScript requirement, not a cascivo-specific issue, but the CSS imports in
our quick-start trip it on a fresh typechecked setup.
**Fix:** add Vite's client types once. Create `src/vite-env.d.ts`:
```ts
///
```
If you don't use Vite's client types (or `noUncheckedSideEffectImports` is on, which `vite/client`
alone doesn't satisfy), declare the CSS module explicitly instead — this is runtime-free, since a
CSS import is a pure side effect and the declaration only satisfies the type checker:
```ts
// src/css.d.ts
declare module '*.css'
```
The `npx cascivo create` scaffold writes `src/vite-env.d.ts` for you; the manual quick-start does
not, so add one of the above when you wire the CSS imports yourself.
Always import the package **specifier** (`@cascivo/react/styles.css`,
`@cascivo/charts/styles.css`), never the physical `dist/` filename — the subpath is an
`exports` alias and the real file (`dist/charts.css`) is an implementation detail that can change.
---
## SSR crash: `Unknown file extension ".css"` (TanStack Start, Vite SSR, Remix, workerd)
**Symptom:** a server-rendered page throws
`Error: Unknown file extension ".css" for …/@cascivo/react/dist//.css`,
and the app silently falls back to client-only rendering.
**Cause:** you're on `@cascivo/react` **< 0.10**, whose bundle ships per-component
CSS as **static side-effect imports** (`import './button.css'` inside each
component chunk). A bundler resolves those at build time, but a bare server-side
ESM loader — Node's native loader, or a workerd/Cloudflare runtime — has no loader
for `.css` and throws.
**Fix — upgrade:** `@cascivo/react` **0.10+** ships a CSS-free `node`-condition
server build, so a bare server loader imports it with **zero config**. Upgrading
makes the crash go away with no `vite.config.ts` change. Still import the aggregate
stylesheet once so the server HTML is styled:
```tsx
// your root route / server entry — once
import '@cascivo/react/styles.css'
import '@cascivo/themes/all.css'
```
**Fix — if pinned to < 0.10:** tell Vite to **process** the cascivo packages
during SSR instead of leaving them for the runtime to load raw:
```ts
// vite.config.ts
export default defineConfig({
ssr: { noExternal: [/^@cascivo\//] }, // ← the < 0.10 fix
})
```
Or add the `cascivoSsr()` plugin from `@cascivo/vite-plugin`, which sets
`ssr.noExternal` for every `@cascivo/*` package. Full recipe (TanStack Start,
Remix, workerd): [USING-WITH-VITE-SSR.md](/docs/using-with-vite-ssr.md).
---
## Build error: `Cannot find module or type declarations for side-effect import` (TS2882)
**Symptom:** TypeScript errors on a theme CSS import —
`error TS2882: Cannot find module or type declarations for side-effect import` on
`import '@cascivo/themes/all'`. Common in the TanStack Start scaffold, which enables
`noUncheckedSideEffectImports` by default.
**Cause:** the extensionless `@cascivo/themes/all` subpath resolves to a `.css`
file, and under `noUncheckedSideEffectImports` TS won't accept a side-effect import
whose specifier lacks a recognized module/extension.
**Fix:** use the `.css`-suffixed specifier — every theme export has a `.css` twin:
```tsx
import '@cascivo/themes/all.css' // not '@cascivo/themes/all'
import '@cascivo/react/styles.css'
```
The `.css` form works in every bundler and every tsconfig, so it's the form all
cascivo docs use. (Related tooling note: `@tanstack/cli create` may drop a nested
`pnpm-workspace.yaml` inside the app; inside an existing pnpm monorepo, delete it so
pnpm doesn't treat the app as its own workspace root.)
---
## Handlers fire but the UI never updates (toggles don't toggle, modals don't open)
This is the one failure that gives you nothing to search for: no error, no warning, no
red console. Every filter, sort, and toggle does nothing, and it looks like your event
handlers are broken. They aren't — **nothing subscribed the component to the signal.**
**Cause:** a component of **yours** reads a signal's `.value` during render without
subscribing. React apps get no Babel signals transform, so a subscription has to come
from somewhere.
**Fix — it depends where the signal came from:**
| Where your signal came from | What you need |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| A cascivo hook — `useSignalState`, `useSignal`, `useComputed`, `useDisclosure`, `useMachine`, `useTheme`, … | **Nothing.** These subscribe you automatically. (On `@cascivo/core` < 0.6, `useSignal`/`useComputed` did **not** — upgrade, or add `useSignals()`.) |
| A module-level `signal()`, or a signal passed in as a prop | `useSignals()` as the component's first statement |
| `currentLocale()` from `@cascivo/i18n` (a plain function, so it can't subscribe you) | `useSignals()` as the component's first statement |
```tsx
import { signal } from '@cascivo/core'
import { useSignals } from '@cascivo/react' // or '@cascivo/core' on the copy-paste path
const isOpen = signal(false) // module-level: NOT a hook
function MyPanel() {
useSignals() // ← first statement, because `isOpen` is a raw signal
return (isOpen.value = false)} />
}
```
With a hook-created signal, no `useSignals()` is needed at all:
```tsx
import { useSignalState } from '@cascivo/react'
function MyPanel() {
const [isOpen, setIsOpen] = useSignalState(false) // subscribes this component for you
return setIsOpen(false)} />
}
```
Write a hook-created signal through its setter, as here, rather than `isOpen.value = false`:
the assignment is what the React Compiler and `react-hooks/immutability` reject (see the
first entry on this page). Assigning a module-level signal, as above, is fine.
**Which package do I import from?** `@cascivo/react` on the prebuilt path (Path B) —
every primitive is re-exported there, so you never add `@cascivo/core` to your
`package.json`. `@cascivo/core` on the copy-paste path (Path A). See
[HEADLESS.md](/docs/headless.md#when-do-i-need-usesignals).
**Still frozen?** `useSignals()` starts tracking where it is called, so put it first —
above any signal read.
---
## My CSS doesn't override cascivo styles
**Cause:** cascivo ships everything in cascade layers
(`cascivo.base < cascivo.theme < cascivo.component`). If your override is
_inside a layer_ that is ordered before `cascivo.component`, it loses no matter
how specific it is.
**Fix:** unlayered author CSS beats **every** cascivo layer regardless of
specificity — a plain stylesheet override just wins. To override from within a
layer, declare your layer ordered _after_ `cascivo.component`.
The inverse pitfall also exists: a global reset like `* { margin: 0; padding: 0 }`
written **outside** any layer beats all cascivo layers too, zeroing out every
component's padding. Wrap resets in a lowest-priority layer. Full recipe:
[CSS-LAYERS-PITFALL.md](/docs/css-layers-pitfall.md).
---
## A third-party library's CSS is overriding my cascivo styles
**Cause:** the library ships an unlayered global stylesheet, and unlayered author
CSS beats every cascivo layer regardless of specificity.
**Fix:** import the vendor CSS into a low-priority `vendor` layer declared before the
cascivo layers — `@import url('lib/styles.css') layer(vendor);`. Native CSS, no build
tooling. If you're importing the stylesheet from JavaScript
(`import 'lib/styles.css'`), it can't be layered from there — move it into a CSS file
first. Full recipe: [THIRD-PARTY-CSS.md](/docs/third-party-css.md).
---
## My `:root` token override doesn't apply until `data-theme` is set
**Cause:** the specificity footgun. Themes ship a
`:root:not([data-theme])` default with specificity (0,2,0), which beats a plain
`:root { --cascivo-color-accent: … }` at (0,1,0) — so your override silently
loses in the no-attribute state.
**Fix:** mirror the theme's selector list inside `@layer cascivo.theme` and
import your file after the cascivo themes, or override from genuinely unlayered
CSS. The recommended pattern (a brand indirection variable) is in
[THEMING.md](/docs/theming.md#the-specificity-footgun-read-this-before-writing-a-brand-theme).
---
## `cascivo add` / `cascivo list` fails offline or the registry is unreachable
**Behavior:** the registry _index_ is fetched network-first with an offline
fallback — the CLI caches every fetched copy under `~/.cascivo/cache` and, when
the network fails, falls back to the last cached copy with a
`Could not reach … — using the last cached copy.` notice. Component _file
payloads_ are never cached (they must be fresh, and a truncated install must
fail), so `cascivo add` itself needs a working connection.
**Fix:** check connectivity and the `registry` URL in `cascivo.config.ts`
(default `https://cascivo.com/registry.json`). A
`Network error fetching …` message after four retries means the host is
genuinely unreachable, not that your config is broken.
---
## The docs sites are unreachable (403 from npmjs.com, blocked/offline cascivo.com)
**Cause:** `npmjs.com` returns HTTP 403 to non-browser fetches, and `cascivo.com`
may be blocked by a corporate proxy, uncrawlable page-by-page, or simply offline.
AI agents and firewalled setups hit this often.
**Fix:** read the docs from the npm **registry** instead — the same channel that
installed your packages. The entire docs surface ships as
[`@cascivo/docs`](https://www.npmjs.com/package/@cascivo/docs), usable with no
install:
```sh
npx -y @cascivo/docs # the index (llms.txt)
npx -y @cascivo/docs button # one component's reference
npx -y @cascivo/docs guide theming # a concept guide
npx -y @cascivo/docs --full # the entire library, one file
npx -y @cascivo/docs --list # every available doc path
```
No npm at all? `npm pack @cascivo/docs` (or `curl` the registry tarball) and read
`content/llms-full.txt`. The package is republished with every release, so its
copy never lags the packages.
---
## A component looks or behaves differently than the docs show
**Cause:** version drift. Docs and Storybook track the registry head; your copy
(or installed package) may be older — or you edited a copied component and
forgot.
**Fix:**
```sh
npx cascivo update --check # copied components: lists what changed upstream
npx cascivo update # three-way merge of upstream changes
```
For the prebuilt packages, compare your installed versions against
`breaking-changes.json` (every major/minor release per package with notes) —
see [UPGRADING.md](/docs/upgrading.md).
---
## Popover / Sheet / Drawer doesn't open in an older browser
**Cause:** overlay components are built on the Popover API and
`@starting-style`, supported in Chrome 114+, Firefox 125+, and Safari 17.4+.
cascivo targets the last 2 versions of Chrome, Firefox, and Safari; older
browsers are outside the support matrix.
**Fix:** check the feature table in [COMPATIBILITY.md](/docs/compatibility.md). Note
`Modal` uses the native `