# Troubleshooting Guide
Common issues and solutions when using Grimoire v3.
---
## 🔍 Quick Diagnosis
### Symptoms by Category
- **[Ref Access Issues](#ref-access-issues)** - "Cannot read property X of null/undefined"
- **[Import Errors](#import-errors)** - Module not found, type errors
- **[Icon Issues](#icon-issues)** - Icons not showing or wrong color
- **[TypeScript Errors](#typescript-errors)** - Type errors, inference issues
- **[Build Errors](#build-errors)** - Build/compilation failures
- **[Runtime Errors](#runtime-errors)** - Errors in the console at runtime
- **[Styling Issues](#styling-issues)** - Components not styled correctly
---
## 🎯 Ref Access Issues
### Issue: "Cannot read property 'open' of null"
**Symptom:**
```javascript
dropdownRef.value.open(); // TypeError: Cannot read property 'open' of null
```
**Cause:** Trying to access ref before component is mounted.
**Fix:**
Use optional chaining:
```javascript
// ✅ Correct
dropdownRef.value?.open();
```
Or wait for mount:
```javascript
import { onMounted } from 'vue';
onMounted(() => {
dropdownRef.value?.open(); // Safe
});
```
---
### Issue: "Cannot read property 'open' of undefined"
**Symptom:**
```javascript
dropdownRef.open(); // TypeError: Cannot read property 'open' of undefined
```
**Cause:** Forgot `.value` in Composition API.
**Fix:**
```javascript
// ❌ Wrong - missing .value
dropdownRef.open();
// ✅ Correct
dropdownRef.value.open();
```
---
### Issue: "@refMounted event not firing"
**Symptom:** In v3, `@refMounted` doesn't work anymore.
**Cause:** `@refMounted` was removed in v3.
**Fix:** Use direct refs instead.
**OLD (v2):**
```vue
```
**NEW (v3):**
```vue
```
See [`v2-to-v3-migration-guide.md`](./v2-to-v3-migration-guide.md) for complete migration guide.
---
## 📦 Import Errors
### Issue: "Cannot find module '@twentyfourg/grimoire/composables'"
**Symptom:**
```
Error: Cannot find module '@twentyfourg/grimoire/composables'
```
**Cause:** Package not built or wrong version.
**Fix:**
1. Update to v3:
```bash
pnpm update @twentyfourg/grimoire@^3.0.0
```
2. Clear node_modules:
```bash
rm -rf node_modules pnpm-lock.yaml
pnpm install
```
3. Restart dev server
---
### Issue: "Cannot find module '@twentyfourg/grimoire/plugin'"
**Symptom:**
```
Error: Cannot find module '@twentyfourg/grimoire/plugin'
```
**Cause:** Using old default import syntax.
**Fix:**
**OLD (v2):**
```javascript
import GrimoirePlugin from '@twentyfourg/grimoire/plugin';
```
**NEW (v3):**
```javascript
import { GrimoirePlugin } from '@twentyfourg/grimoire/plugin';
```
---
### Issue: "Module has no exported member 'GButton'"
**Symptom:**
```
Module '"@twentyfourg/grimoire"' has no exported member 'GButton'
```
**Cause:** Component doesn't exist or wrong package.
**Fix:**
Check component name:
```javascript
// ✅ Correct - capitalized G
import { GButton, GInput } from '@twentyfourg/grimoire';
// ❌ Wrong
import { Button, Input } from '@twentyfourg/grimoire';
```
Verify component exists:
```bash
# List all exports
cat node_modules/@twentyfourg/grimoire/dist/index.d.ts
```
---
## 🎨 Icon Issues
### Issue: Icons not showing
**Symptom:** `` renders but no icon visible.
**Cause:** Icons not registered with plugin.
**Fix:**
```javascript
// main.ts
import { GrimoirePlugin } from '@twentyfourg/grimoire/plugin';
import { icons } from './icons-bundle.js'; // Make sure this exists
app.use(GrimoirePlugin, { icons }); // Register icons
```
Check console for warnings:
```
[Iconify] Icon not found: app:home
```
---
### Issue: Icons not updating after SVG changes
**Symptom:** Changed SVG file but icon doesn't update.
**Cause:** Vite not rebuilding icon bundle.
**Fix:**
1. Enable verbose mode:
```typescript
viteIconBundlePlugin({
verbose: true, // See build logs
sources: [...]
});
```
2. Restart dev server:
```bash
pnpm dev
```
3. Force rebuild:
```bash
rm -rf node_modules/.vite
pnpm dev
```
---
### Issue: Icons wrong color
**Symptom:** Icon shows original color when it should inherit text color.
**Cause:** Using colored variant instead of monotone.
**Fix:**
```vue
```
Or configure monotone variant:
```typescript
viteIconBundlePlugin({
sources: [
{
type: 'folder',
path: 'icons',
prefix: 'app',
variants: 'monotone', // Only create monotone version
},
],
});
```
---
## 🔧 TypeScript Errors
### Issue: "Property 'value' does not exist on type 'Ref'"
**Symptom:**
```typescript
const buttonRef = ref(null);
buttonRef.value.focus(); // Error
```
**Cause:** Incorrect ref typing.
**Fix:**
```typescript
import { ref } from 'vue';
import type { ComponentPublicInstance } from 'vue';
import { GButton } from '@twentyfourg/grimoire';
// ✅ Correct
const buttonRef = ref(null);
// Or
const buttonRef = ref | null>(null);
```
---
### Issue: "Type 'string' is not assignable to type 'never'"
**Symptom:**
```typescript
const form = reactive({
name: '',
email: '',
}); // Type error
```
**Cause:** TypeScript can't infer type from empty strings.
**Fix:**
Be explicit:
```typescript
interface Form {
name: string;
email: string;
}
const form = reactive