# Common Issues
This document covers frequently encountered problems and their solutions when working with PatternFly React applications.
## Introduction
PatternFly development can present various challenges ranging from setup issues to component-specific problems. This guide provides systematic approaches to diagnosing and resolving common issues that AI coders encounter when building PatternFly applications.
## Related Files
- [**Setup Guide**](../setup/README.md) - Initial setup troubleshooting
- [**External References**](../resources/external-links.md) - Additional troubleshooting resources
## AI Coding Specific Issues
### Component Generation Issues
#### Issue: AI generates non-existent PatternFly components
```jsx
// ❌ AI might generate these (they don't exist)
<TextContent>Title</TextContent>
<EmptyStateHeader>No data</EmptyStateHeader>
<TableHeader />
```
**Solutions**:
1. **Use correct v6 components**:
```jsx
// ✅ Correct v6 components
import { Content, EmptyState, EmptyStateBody, EmptyStateHeader } from '@patternfly/react-core';
<Content component="h1">Title</Content>
<EmptyState>
<EmptyStateHeader titleText="No data" />
<EmptyStateBody>Description goes here</EmptyStateBody>
</EmptyState>
```
2. **Always verify component existence** - Check [PatternFly.org](https://www.patternfly.org/) before using
#### Issue: AI uses CSS modules syntax
```jsx
// ❌ Wrong - This doesn't work in this project
<div className={styles.customClass}>
```
**Solutions**:
1. **Use PatternFly utility classes**:
```jsx
// ✅ Correct - Use PatternFly utilities
<div className="pf-v6-u-margin-md pf-v6-u-text-align-center">
```
2. **Use CSS-in-JS for custom styles**:
```jsx
// ✅ Alternative - Inline styles when utilities don't exist
<div style={{ margin: 'var(--pf-t--global--spacer--md)' }}>
```
#### Issue: AI uses inline styles instead of PatternFly utilities
```jsx
// ❌ Wrong - Avoid inline styles for layout/spacing
<div style={{ margin: 16, textAlign: 'center' }}>
```
**Solutions**:
1. **Use proper PatternFly component composition**:
```jsx
// ✅ Correct - Use proper component hierarchy
<PageSection>
<Stack hasGutter>
<Title headingLevel="h1" size="lg">Content</Title>
<Content>Content description</Content>
</Stack>
</PageSection>
```
2. **For custom styles, use design tokens**:
```jsx
// ✅ Only when component composition isn't sufficient
<div style={{
margin: 'var(--pf-t--global--spacer--md)',
color: 'var(--pf-t--global--text--color--regular)'
}}>
```
### Accessibility Issues
#### Issue: AI generates components without accessibility features
```jsx
// ❌ Not accessible
<Card onClick={handleClick}>
<CardBody>Clickable content</CardBody>
</Card>
```
**Solutions**:
1. **Add proper ARIA attributes**:
```jsx
// ✅ Accessible
<Card
isClickable
onClick={handleClick}
tabIndex={0}
role="button"
aria-label="View details"
onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
<CardBody>Clickable content</CardBody>
</Card>
```
2. **Use PatternFly's built-in accessibility props**:
```jsx
// ✅ Use component's accessibility features
<Card
selectableActions={{
selectableActionAriaLabel: "View card details"
}}
onSelectableInputChange={handleClick}
>
```
### Chart Integration Issues
#### Issue: Wrong chart import paths
```bash
# Error message
Module not found: Can't resolve '@patternfly/react-charts'
```
**Solutions**:
1. **Use correct import paths**:
```jsx
// ✅ Correct - Include /victory
import { ChartDonut, ChartLine } from '@patternfly/react-charts/victory';
// ❌ Wrong - Missing /victory
import { ChartDonut } from '@patternfly/react-charts';
```
2. **Install missing dependencies**:
```bash
npm install @patternfly/react-charts victory
```
#### Issue: AI uses wrong chart colors
```jsx
// ❌ Wrong - Hardcoded colors
<ChartDonut colorScale={['#333', '#666', '#999']} />
```
**Solutions**:
1. **Use PatternFly chart color tokens**:
```jsx
// ✅ Correct - Use design tokens
const chartColors = [
'var(--pf-t-chart-color-blue-300)',
'var(--pf-t-chart-color-green-300)',
'var(--pf-t-chart-color-orange-300)'
];
<ChartDonut colorScale={chartColors} />
```
### Chatbot Implementation Issues
#### Issue: AI creates custom chat UI instead of using PatternFly Chatbot
```jsx
// ❌ Wrong - Custom chat implementation
<div className="custom-chat">
<div className="messages">...</div>
<input type="text" />
</div>
```
**Solutions**:
1. **Use PatternFly Chatbot components**:
```jsx
// ✅ Correct - Use PatternFly Chatbot
import { Chatbot, ChatbotContent, MessageBox } from '@patternfly/chatbot/dist/dynamic/Chatbot';
import '@patternfly/chatbot/dist/css/main.css';
<Chatbot>
<ChatbotContent>
<MessageBox>
{/* Messages */}
</MessageBox>
</ChatbotContent>
</Chatbot>
```
2. **Follow official demo patterns** - Copy from [PatternFly Chatbot demos](https://www.patternfly.org/patternfly-ai/chatbot/overview)
### Styling and Layout Issues
#### Issue: AI mixes PatternFly versions
```jsx
// ❌ Wrong - Mixed versions
<div className="pf-v5-c-button pf-v6-u-margin-md">
```
**Solutions**:
1. **Use PatternFly v6 only**:
```jsx
// ✅ Correct - v6 only
<Button className="pf-v6-u-margin-md">
```
#### Issue: Spacing and layout inconsistencies
```jsx
// ❌ Poor spacing
<div>
<Button>Save</Button>
<Button>Cancel</Button>
</div>
```
**Solutions**:
1. **Use proper PatternFly component composition**:
```jsx
// ✅ Proper spacing using ActionGroup component
<ActionGroup>
<Button variant="primary">Save</Button>
<Button variant="secondary">Cancel</Button>
</ActionGroup>
```
## Setup Issues
### Node.js and npm Problems
#### Issue: Command not found errors
```bash
# Error messages
'node' is not recognized as an internal or external command
'npm' is not recognized as an internal or external command
```
**Solutions**:
1. **Verify Installation**:
```bash
# Check if Node.js is installed
node --version
npm --version
```
2. **Reinstall Node.js**:
- Download from [https://nodejs.org/](https://nodejs.org/)
- Choose LTS version for stability
- Restart terminal after installation
3. **PATH Configuration**:
```bash
# Windows: Add to PATH environment variable
C:\Program Files\nodejs\
# macOS/Linux: Add to shell profile
export PATH="/usr/local/bin/node:$PATH"
```
#### Issue: npm permission errors
```bash
# Error message
EACCES: permission denied, access '/usr/local/lib/node_modules'
```
**Solutions**:
1. **Use nvm (Recommended)**:
```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install and use Node.js
nvm install node
nvm use node
```
2. **Fix npm permissions**:
```bash
# Create global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to PATH
export PATH=~/.npm-global/bin:$PATH
```
### Project Setup Issues
#### Issue: Git clone failures
```bash
# Error message
fatal: repository 'https://github.com/patternfly/patternfly-react-seed' not found
```
**Solutions**:
1. **Check Network Connection**: Verify internet connectivity
2. **Use HTTPS instead of SSH**:
```bash
git clone https://github.com/patternfly/patternfly-react-seed
```
3. **Check Repository URL**: Verify the repository exists and URL is correct
#### Issue: npm install failures
```bash
# Error messages
npm ERR! network request failed
npm ERR! peer dep missing
```
**Solutions**:
1. **Clear npm cache**:
```bash
npm cache clean --force
```
2. **Delete node_modules and reinstall**:
```bash
rm -rf node_modules package-lock.json
npm install
```
3. **Check npm registry**:
```bash
npm config get registry
# Should return: https://registry.npmjs.org/
```
4. **Install with legacy peer deps**:
```bash
npm install --legacy-peer-deps
```
### Development Server Issues
#### Issue: Port already in use
```bash
# Error message
Error: listen EADDRINUSE: address already in use :::9000
```
**Solutions**:
1. **Find and kill process**:
```bash
# Windows
netstat -ano | findstr :9000
taskkill /PID <PID> /F
# macOS/Linux
lsof -ti:9000 | xargs kill -9
```
2. **Use different port**:
```bash
PORT=3001 npm run start:dev
```
3. **Update package.json**:
```json
{
"scripts": {
"start:dev": "webpack serve --port 3001"
}
}
```
#### Issue: Development server not starting
```bash
# Error message
Module not found: Error: Can't resolve 'webpack-dev-server'
```
**Solutions**:
1. **Reinstall dependencies**:
```bash
rm -rf node_modules package-lock.json
npm install
```
2. **Check webpack configuration**:
```javascript
// Verify webpack.config.js exists and is properly configured
```
3. **Install missing dependencies**:
```bash
npm install webpack webpack-dev-server --save-dev
```
## Import and Module Issues
### PatternFly Component Import Errors
#### Issue: Module not found errors
```bash
# Error message
Module not found: Can't resolve '@patternfly/react-core'
```
**Solutions**:
1. **Install PatternFly packages**:
```bash
npm install @patternfly/react-core @patternfly/react-table @patternfly/react-icons
```
2. **Check import syntax**:
```jsx
// Correct imports
import { Button, Card } from '@patternfly/react-core';
import { Table, Thead, Tbody } from '@patternfly/react-table';
import { UserIcon } from '@patternfly/react-icons';
```
3. **Verify package.json dependencies**:
```json
{
"dependencies": {
"@patternfly/react-core": "^6.x.x",
"@patternfly/react-table": "^6.x.x",
"@patternfly/react-icons": "^6.x.x"
}
}
```
#### Issue: Charts module not found
```bash
# Error message
Module not found: Can't resolve '@patternfly/react-charts/victory'
```
**Solutions**:
1. **Install charts dependencies**:
```bash
npm install @patternfly/react-charts victory
```
2. **Use correct import paths**:
```jsx
// Correct chart imports
import { ChartDonut, ChartLine } from '@patternfly/react-charts/victory';
```
3. **Clear cache and reinstall**:
```bash
rm -rf node_modules package-lock.json
npm install
```
#### Issue: Chatbot module not found
```bash
# Error message
Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot'
```
**Solutions**:
1. **Install chatbot package**:
```bash
npm install @patternfly/chatbot
```
2. **Import CSS**:
```jsx
import '@patternfly/chatbot/dist/css/main.css';
```
3. **Use correct import paths**:
```jsx
import { Chatbot } from '@patternfly/chatbot/dist/dynamic/Chatbot';
```
## Styling Issues
### CSS and Class Problems
#### Issue: PatternFly styles not applied
```bash
# Symptoms: Components appear unstyled or with default browser styles
```
**Solutions**:
1. **Import PatternFly CSS**:
```jsx
// In your main App.js or index.js
import '@patternfly/react-core/dist/styles/base.css';
```
2. **Check CSS import order**:
```jsx
// PatternFly CSS should be imported before custom CSS
import '@patternfly/react-core/dist/styles/base.css';
import './custom-styles.css';
```
3. **Verify webpack CSS handling**:
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader']
}
]
}
};
```
#### Issue: Wrong PatternFly version classes
```jsx
// Problem: Using old class names
<div className="pf-c-button"> // v4 class
<div className="pf-v5-c-button"> // v5 class
```
**Solutions**:
1. **Use PatternFly v6 classes**:
```jsx
// Correct v6 classes
<div className="pf-v6-c-button">
<div className="pf-v6-u-margin-md">
```
2. **Update class references**:
```bash
# Find and replace old classes
grep -r "pf-c-" src/
grep -r "pf-v5-" src/
```
3. **Use PatternFly components instead**:
```jsx
// Instead of manual classes, use components
import { Button } from '@patternfly/react-core';
<Button variant="primary">Click me</Button>
```
#### Issue: PatternFly utility class styles not applied
```bash
# Symptoms: Adding utility classes (pf-v6-u-*) do not have any apparent effect
```
**Solutions**:
1. **Install patternfly package**:
```bash
npm install @patternfly/patternfly
```
2. **Import PatternFly Utility CSS**:
```jsx
// In your main App.js or index.js
import '@patternfly/patternfly/patternfly-addons.css';
```
3. **Verify webpack CSS handling**:
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader']
}
]
}
};
```
### Layout and Responsive Issues
#### Issue: Components not responsive
```jsx
// Problem: Fixed widths and heights
<div style={{ width: '800px', height: '600px' }}>
```
**Solutions**:
1. **Use PatternFly responsive utilities**:
```jsx
<div className="pf-v6-u-width-100 pf-v6-u-height-auto">
```
2. **Implement responsive patterns**:
```jsx
<div className="pf-v6-l-grid pf-v6-m-gutter">
<div className="pf-v6-l-grid__item pf-v6-m-12-col pf-v6-m-6-col-on-md">
Content
</div>
</div>
```
3. **Use container-based sizing**:
```jsx
const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
useEffect(() => {
const updateDimensions = () => {
if (containerRef.current) {
const { width, height } = containerRef.current.getBoundingClientRect();
setDimensions({ width, height });
}
};
updateDimensions();
window.addEventListener('resize', updateDimensions);
return () => window.removeEventListener('resize', updateDimensions);
}, []);
```
## Component-Specific Issues
### Dropdown Clipping Issues
#### Issue: Dropdown menu gets clipped
```jsx
// Problem: Dropdown appears cut off in scrollable containers
```
**Solutions**:
1. **Use appendTo prop**:
```jsx
<Dropdown
popperProps={{
appendTo: () => document.body,
position: 'right',
enableFlip: true
}}
>
```
2. **Configure positioning**:
```jsx
<Dropdown
popperProps={{
position: 'right',
enableFlip: true,
preventOverflow: true
}}
>
```
### Table Performance Issues
#### Issue: Slow rendering with large datasets
```jsx
// Problem: Table becomes unresponsive with 1000+ rows
```
**Solutions**:
1. **Implement pagination**:
```jsx
import { Pagination } from '@patternfly/react-core';
const [page, setPage] = useState(1);
const [perPage, setPerPage] = useState(20);
const paginatedData = data.slice((page - 1) * perPage, page * perPage);
```
2. **Use virtualization**:
```jsx
import { DndProvider, useDrag, useDrop } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table';
const DraggableRow = ({ id, text, index, moveRow }) => {
// ... existing code ...
```
3. **Optimize re-renders**:
```jsx
const MemoizedRow = React.memo(({ item }) => (
<Tr>
<Td>{item.name}</Td>
<Td>{item.email}</Td>
</Tr>
));
```
## Build and Deployment Issues
### Build Failures
#### Issue: Build process fails
```bash
# Error message
npm ERR! Failed at the build script
```
**Solutions**:
1. **Check for TypeScript errors**:
```bash
npx tsc --noEmit
```
2. **Verify all imports**:
```bash
# Check for unused imports
npm run lint
```
3. **Clear build cache**:
```bash
rm -rf dist/ build/
npm run build
```
#### Issue: Bundle size too large
```bash
# Warning: Bundle size exceeds recommended limit
```
**Solutions**:
1. **Analyze bundle**:
```bash
npm install --save-dev webpack-bundle-analyzer
npx webpack-bundle-analyzer dist/
```
2. **Implement code splitting**:
```jsx
const LazyComponent = React.lazy(() => import('./HeavyComponent'));
<Suspense fallback={<Spinner />}>
<LazyComponent />
</Suspense>
```
3. **Tree shake unused code**:
```javascript
// webpack.config.js
module.exports = {
optimization: {
usedExports: true,
sideEffects: false
}
};
```
## Browser Compatibility Issues
### Cross-Browser Problems
#### Issue: Components not working in specific browsers
```bash
# Symptoms: Features work in Chrome but not Safari/Firefox
```
**Solutions**:
1. **Check browser support**:
```json
// package.json
"browserslist": [
"> 1%",
"last 2 versions",
"not dead"
]
```
2. **Add polyfills**:
```bash
npm install core-js
```
```jsx
// index.js
import 'core-js/stable';
```
3. **Test across browsers**:
- Use browser dev tools
- Test on actual devices
- Use browser testing services
## Debugging Strategies
### General Debugging Approach
1. **Check Console**: Look for error messages and warnings
2. **Isolate Problem**: Create minimal reproduction case
3. **Verify Versions**: Ensure compatible package versions
4. **Check Documentation**: Reference official PatternFly docs
5. **Search Issues**: Look for similar problems in GitHub issues
### Debug Tools
- **React DevTools**: Inspect component state and props
- **Browser DevTools**: Network, console, and element inspection
- **PatternFly DevTools**: PatternFly-specific debugging
- **Bundle Analyzer**: Analyze build output and dependencies
### Getting Help
1. **GitHub Issues**: Search and create issues with minimal reproduction
2. **Stack Overflow**: Use `patternfly` tag for questions
3. **Community Slack**: Real-time help from community
4. **Documentation**: Always check latest official documentation
## Prevention Strategies
### Best Practices
- **Keep Dependencies Updated**: Regularly update PatternFly packages
- **Follow Semantic Versioning**: Use compatible version ranges
- **Test Incrementally**: Test changes in small increments
- **Use Linting**: Implement ESLint and Prettier
- **Document Issues**: Keep track of solutions for future reference
### Code Quality
- **Type Safety**: Use TypeScript when possible
- **Testing**: Write unit tests for components
- **Code Review**: Review changes for PatternFly compliance
- **Performance Monitoring**: Track bundle size and performance metrics
Remember: When encountering issues, always check the [official PatternFly documentation](https://www.patternfly.org/) first, then search [GitHub issues](https://github.com/patternfly/patternfly-react/issues) for similar problems. Provide specific error messages, code snippets, and version information when seeking help.
