Documentation
Troubleshooting
Common issues and solutions when using Angular AI Kit.
Quick Checklist
First things to check when something isn't working
- 1Check console for errors (F12 → Console)
- 2Verify all dependencies are installed (
npm ls @angular-ai-kit/core) - 3Clear cache and rebuild (
npm cache clean --force && npm install) - 4Check Angular version compatibility (17+ required)
- 5Restart development server after configuration changes
Installation Issues
Problems during package installation
Error: Module not found
Cannot find module '@angular-ai-kit/core' or its corresponding type declarations.
1// Check your tsconfig.json paths2{3 "compilerOptions": {4 "paths": {5 "@angular-ai-kit/*": ["./node_modules/@angular-ai-kit/*"]6 }7 }8}9 10// Or try reinstalling11npm install @angular-ai-kit/core @angular-ai-kit/utilsStyling Issues
Components not styled correctly
Tailwind styles not applying
Components appear unstyled or with default browser styles.
1// postcss.config.js (Tailwind v4)2export default {3 plugins: {4 '@tailwindcss/postcss': {},5 },6};7 8// styles.css9@import "tailwindcss";10 11// angular.json - ensure styles are included12"styles": [13 "src/styles.css"14]CSS variables not defined
Colors showing as default or undefined.
1:root {2 /* Required CSS variables */3 --background: theme('colors.white');4 --foreground: theme('colors.zinc.950');5 --card: theme('colors.zinc.50');6 --card-foreground: theme('colors.zinc.950');7 --muted: theme('colors.zinc.100');8 --muted-foreground: theme('colors.zinc.500');9 --accent: theme('colors.zinc.100');10 --accent-foreground: theme('colors.zinc.900');11 --border: theme('colors.zinc.200');12 --input: theme('colors.zinc.200');13 --ring: theme('colors.zinc.400');14 --primary: theme('colors.zinc.900');15 --primary-foreground: theme('colors.zinc.50');16}17 18.dark {19 --background: theme('colors.zinc.950');20 --foreground: theme('colors.zinc.50');21 /* ... dark mode values */22}ViewEncapsulation blocking styles
Tailwind classes not working in components.
1import { ViewEncapsulation } from '@angular/core';2 3@Component({4 selector: 'app-chat',5 encapsulation: ViewEncapsulation.None, // Required for Tailwind6 template: `...`,7})8export class ChatComponent {}Runtime Issues
Errors during application execution
Signal.mutate() is deprecated
TypeScript error or runtime warning about mutate.
1// ❌ Wrong - mutate() is deprecated2this.messages.mutate(msgs => {3 msgs.push(newMessage);4});5 6// ✅ Correct - use update()7this.messages.update(msgs => [...msgs, newMessage]);8 9// ✅ Or use set() for full replacement10this.messages.set([...this.messages(), newMessage]);Memory leaks from subscriptions
Application slowing down over time or duplicate subscriptions.
1// Use DestroyRef for cleanup2private destroyRef = inject(DestroyRef);3 4ngOnInit() {5 this.subscription = this.service.data$.subscribe(/* ... */);6 7 this.destroyRef.onDestroy(() => {8 this.subscription.unsubscribe();9 });10}11 12// Or use takeUntilDestroyed()13import { takeUntilDestroyed } from '@angular/core/rxjs-interop';14 15this.service.data$16 .pipe(takeUntilDestroyed())17 .subscribe(/* ... */);Changes not reflecting in UI
Data updates but UI doesn't refresh (OnPush components).
1// Force change detection for async updates2private cdr = inject(ChangeDetectorRef);3 4async loadData() {5 const data = await this.api.fetch();6 this.data.set(data);7 this.cdr.markForCheck(); // Trigger change detection8}9 10// Or use signals which auto-trigger updates11data = signal<Data | null>(null);12 13async loadData() {14 const data = await this.api.fetch();15 this.data.set(data); // Auto-triggers CD16}API Integration Issues
Problems connecting to AI APIs
Streaming not working
Response comes all at once instead of streaming.
1// Check your backend is sending SSE format2res.setHeader('Content-Type', 'text/event-stream');3res.setHeader('Cache-Control', 'no-cache');4res.setHeader('Connection', 'keep-alive');5 6// Each chunk should be formatted as:7res.write(`data: ${JSON.stringify(chunk)}\n\n`);8 9// End with:10res.write('data: [DONE]\n\n');11res.end();CORS errors
"Access-Control-Allow-Origin" errors in console.
1// Backend - Add CORS headers2app.use((req, res, next) => {3 res.header('Access-Control-Allow-Origin', 'http://localhost:4200');4 res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');5 res.header('Access-Control-Allow-Headers', 'Content-Type');6 next();7});8 9// Or use Angular proxy for development10// proxy.conf.json11{12 "/api": {13 "target": "http://localhost:3000",14 "secure": false,15 "changeOrigin": true16 }17}SSR / Hydration Issues
Server-side rendering problems
window/document is not defined
Errors during server-side rendering.
1// Check for browser before accessing DOM2import { isPlatformBrowser } from '@angular/common';3import { PLATFORM_ID, inject } from '@angular/core';4 5export class MyComponent {6 private platformId = inject(PLATFORM_ID);7 8 scrollToBottom() {9 if (isPlatformBrowser(this.platformId)) {10 // Safe to access DOM11 window.scrollTo(0, document.body.scrollHeight);12 }13 }14}Debugging Tips
How to diagnose issues
Check Network Tab
F12 → Network → Look for failed requests, check response format
Use Angular DevTools
Install the Chrome extension to inspect components and signals
Add console.log
Log signal values with console.log(signal())
Inspect Elements
F12 → Elements → Check applied CSS classes and computed styles
Need More Help?
If you're still stuck, reach out through these channels: