secondsky/claude-skills / plugins/pinia-colada/skills/pinia-colada
pinia-colada
VerifiedPinia Colada data fetching for Vue/Nuxt with useQuery, useMutation. Use for async state, query cache, SSR, or encountering invalidation, hydration, TanStack Vue Query migration errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.1 KB |
| references/common-patterns.md | markdown | 7.2 KB |
| references/configuration.md | markdown | 9.8 KB |
| references/error-catalog.md | markdown | 5.9 KB |
| references/migration-from-tanstack-vue-query.md | markdown | 11.4 KB |
| references/setup-guide.md | markdown | 12.6 KB |
references/error-catalog.md
View on GitHub# Pinia Colada Error Catalog
Complete catalog of 12 documented errors with sources, causes, and solutions.
---
## Error #1: Query Not Refetching After Mutation
**Error**: Data doesn't update in UI after successful mutation
**Source**: https://github.com/posva/pinia-colada/discussions/315
**Why It Happens**: Forgot to invalidate queries in mutation hooks
**Solution**: Always use `invalidateQueries` in `onSettled`:
```typescript
useMutation({
mutation: createTodo,
async onSettled() {
await queryCache.invalidateQueries({ key: ['todos'] })
},
})
```
---
## Error #2: Race Condition with Optimistic Updates
**Error**: Optimistic update gets overwritten by in-flight request
**Source**: https://github.com/posva/pinia-colada/issues/53
**Why It Happens**: Didn't cancel ongoing queries before optimistic update
**Solution**: Always call `cancelQueries` in `onMutate`:
```typescript
onMutate(id) {
cache.cancelQueries({ key: ['todos'] })
// Then do optimistic update
}
```
---
## Error #3: SSR Hydration Mismatch
**Error**: `Hydration completed but contains mismatches`
**Source**: Nuxt SSR documentation
**Why It Happens**: Client refetches on mount with different data than server
**Solution**: Set `refetchOnMount: false` for SSR queries
```typescript
useQuery({
key: ['todos'],
query: fetchTodos,
refetchOnMount: false, // Prevents SSR hydration mismatch
})
```
---
## Error #4: Query Key Not Reactive
**Error**: Query doesn't refetch when variable changes
**Why It Happens**: Key is static array instead of function
**Solution**: Use function for reactive keys:
```typescript
// ❌ Wrong - static key
key: ['todos', id.value]
// ✅ Correct - reactive key
key: () => ['todos', id.value]
```
---
## Error #5: Mutation onSuccess Doesn't Await Invalidation
**Error**: Modal closes before data refreshes, showing stale data
**Why It Happens**: `invalidateQueries` not awaited
**Solution**: Always await invalidation:
```typescript
async onSettled() {
await cache.invalidateQueries({ key: ['todos'] })
// Now safe to continue
}
```
---
## Error #6: Cannot Read Property of Undefined
**Error**: `Cannot read property 'map' of undefined`
**Why It Happens**: Using `data.value` before it's defined
**Solution**: Always check or provide fallback:
```typescript
// ✅ With optional chaining
const todos = computed(() => data.value?.todos ?? [])
// ✅ With v-if
<ul v-if="data">
<li v-for="todo in data" :key="todo.id">
```
---
## Error #7: Query Invalidation Doesn't Work
**Error**: `invalidateQueries` doesn't refetch query
**Why It Happens**: Key mismatch (different key structure)
**Solution**: Use exact same key structure:
```typescript
// Query
useQuery({ key: ['todos', { status: 'active' }], ... })
// Invalidation - must match
cache.invalidateQueries({ key: ['todos', { status: 'active' }] })
// Or invalidate by prefix
cache.invalidateQueries({ key: ['todos'] }) // Catches all
```
---
## Error #8: Memory Leak from Unused Queries
**Error**: App becomes slow over time, high memory usage
**Why It Happens**: `gcTime` set too high or to Infinity
**Solution**: Use reasonable `gcTime` (5-60 minutes):
```typescript
app.use(PiniaColada, {
query: {
gcTime: 5 * 60 * 1000, // 5 minutes (not Infinity)
},
})
```
---
## Error #9: Mutation Error Not Handled
**Error**: Unhandled promise rejection in console
**Why It Happens**: Using `mutateAsync` without try/catch
**Solution**: Always handle errors:
```typescript
// With mutate (no try/catch needed)
mutate(variables) // errors in error ref
// With mutateAsync (need try/catch)
try {
await mutateAsync(variables)
} catch (error) {
console.error(error)
}
```
---
## Error #10: Nuxt Module Order Wrong
**Error**: `PiniaColada plugin not found` or SSR errors
**Source**: https://pinia-colada.esm.dev/nuxt.html
**Why It Happens**: `@pinia/colada-nuxt` loaded before `@pinia/nuxt`
**Solution**: Always put `@pinia/nuxt` first:
```typescript
export default defineNuxtConfig({
modules: [
'@pinia/nuxt', // MUST be first
'@pinia/colada-nuxt', // Then Colada
],
})
```
---
## Error #11: Optimistic Update Lost on Error
**Error**: Optimistic update not rolled back on failure
**Why It Happens**: No rollback logic in `onError`
**Solution**: Always rollback in `onError`:
```typescript
onMutate(id) {
const prev = cache.getQueryData(['todos'])
// ... optimistic update
return { prev }
},
onError(_err, _vars, ctx) {
if (ctx?.prev) {
cache.setQueryData(['todos'], ctx.prev)
}
},
```
---
## Error #12: Infinite Refetch Loop
**Error**: Query refetches continuously
**Why It Happens**: Query key changes on every render (object identity)
**Solution**: Memoize or use stable references:
```typescript
// ❌ Wrong - new object every render
key: () => ['todos', { filters: getFilters() }]
// ✅ Correct - stable reference
const filters = ref({ status: 'active' })
key: () => ['todos', filters.value]
```
---
## Prevention Checklist
Use this checklist to prevent all 12 errors:
- [ ] Invalidate queries in mutation `onSettled` hook
- [ ] Cancel queries before optimistic updates (`onMutate`)
- [ ] Set `refetchOnMount: false` for SSR queries
- [ ] Use function for reactive query keys: `key: () => [...]`
- [ ] Await `invalidateQueries()` when order matters
- [ ] Check `data.value` for undefined before use
- [ ] Match exact key structure when invalidating
- [ ] Set reasonable `gcTime` (5-60 minutes, not Infinity)
- [ ] Use try/catch with `mutateAsync()` or use `mutate()`
- [ ] Put `@pinia/nuxt` before `@pinia/colada-nuxt` in modules
- [ ] Implement rollback in `onError` for optimistic updates
- [ ] Use stable references for query keys (refs, not computed functions)
---
## Official Documentation
- **Pinia Colada**: https://pinia-colada.esm.dev/
- **Troubleshooting**: https://pinia-colada.esm.dev/cookbook/troubleshooting.html
- **GitHub Issues**: https://github.com/posva/pinia-colada/issues
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |