Troubleshooting

Common Issues

Flags Not Updating

Symptom: Changes to flag configuration don't reflect in the application.

Solutions:

1. Restart dev server

   npm run dev

2. Clear build cache

   rm -rf .nuxt
   npm run dev

3. Verify config file path

   // nuxt.config.ts
   export default defineNuxtConfig({
     featureFlags: {
       config: './feature-flags.config.ts'  // Check this path
     }
   })

4. Manually refresh flags on client

   const { fetch } = useFeatureFlags()
   await fetch()

Type Errors

Symptom: TypeScript errors when using flag names, even though flags are defined.

Solutions:

1. Regenerate types

   npx nuxi prepare
   npm run dev

2. Restart TypeScript server

   • In VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

3. Check for typos

   // ❌ Typo
   isEnabled('newDashbord')
   
   // ✅ Correct
   isEnabled('newDashboard')

Variant Assignment Not Working

Symptom: Users are not being assigned to variants, or assignment is inconsistent.

Solutions:

1. Populate context in middleware

   // server/middleware/user-context.ts
   export default defineEventHandler((event) => {
     const user = await getUserFromSession(event)
     if (user) {
       event.context.user = {
         id: user.id  // This enables consistent variant assignment
       }
     }
   })

2. Check variant weights

   // ❌ Weights exceed 100%
   {
     variants: [
       { name: 'a', weight: 60 },
       { name: 'b', weight: 60 }  // Total: 120%
     ]
   }
   
   // ✅ Correct weights
   {
     variants: [
       { name: 'a', weight: 50 },
       { name: 'b', weight: 50 }  // Total: 100%
     ]
   }

3. Verify flag is enabled

   {
     myFlag: {
       enabled: true,  // Must be true
       variants: [...]
     }
   }

Server/Client Mismatch

Symptom: Flags have different values on server vs client, causing hydration errors.

Solutions:

1. Use v-if for SSR content

   <!-- ❌ v-feature doesn't work in SSR -->
   <div v-feature="'myFlag'">
     Server-rendered content
   </div>
   
   <!-- ✅ Use v-if with composable -->
   <script setup>
   const { isEnabled } = useFeatureFlags()
   </script>
   
   <template>
     <div v-if="isEnabled('myFlag')">
       Server-rendered content
     </div>
   </template>

2. Ensure consistent context

   • Server has user context from event
   • Client fetches flags from server

Flags Not Working in Production

Symptom: Flags work in development but not in production build.

Solutions:

1. Verify config file is included

   export default defineNuxtConfig({
     featureFlags: {
       config: './feature-flags.config.ts'
     }
   })

2. Set environment variables

   NODE_ENV=production
   NUXT_PUBLIC_ENV=production

3. Clear build cache

   rm -rf .nuxt .output
   npm run build

Debugging

Log All Resolved Flags

// Client-side
const { flags } = useFeatureFlags()
console.log('All flags:', flags.value)

// Server-side
export default defineEventHandler((event) => {
  const { flags } = getFeatureFlags(event)
  console.log('Server flags:', flags)
  return { flags }
})

Inspect Specific Flag Details

const { getFlag, isEnabled, getVariant, getValue } = useFeatureFlags()

const flag = getFlag('myExperiment')
console.log('Flag details:', {
  enabled: flag?.enabled,
  value: flag?.value,
  variant: flag?.variant
})

Check Context Population

// Server-side middleware
export default defineEventHandler((event) => {
  console.log('Request context:', {
    user: event.context.user,
    device: event.context.device,
    userId: event.context.userId,
    sessionId: event.context.sessionId
  })
})

Enable Debug Mode

// feature-flags.config.ts
export default defineFeatureFlags((context) => {
  const debug = process.env.DEBUG_FLAGS === 'true'
  
  if (debug) {
    console.log('=== Feature Flags Debug ===')
    console.log('Context:', context)
    console.log('Environment:', process.env.NODE_ENV)
    console.log('===========================')
  }
  
  return {
    // Your flags here
  }
})

# Enable debug mode
DEBUG_FLAGS=true npm run dev

Getting Help

If you're still experiencing issues:

1. Check the documentation: Review relevant sections
2. Search existing issues: Look for similar problems on GitHub Issues
3. Enable debug logging: Use the debugging techniques above
4. Create a minimal reproduction: Isolate the problem
5. Open an issue: Provide debug output, configuration, and steps to reproduce

When opening an issue, include:

• Nuxt version (npx nuxi info)
• Module version
• Your feature flags configuration (sanitized)
• Relevant code snippets
• Error messages or unexpected behavior
• Steps to reproduce