Troubleshooting

Troubleshooting

Common issues and solutions for Button Builder.

Installation Issues

Button Builder Not Showing in Sidebar

Symptoms:

• No "Button Builder" entry in sidebar after installation
• Panel URL returns 404

Solutions:

1. Restart Home Assistant

   • Settings System Restart
   • Wait for full restart to complete

2. Clear browser cache

   • Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
   • Or clear browser cache/cookies

3. Check installation path

   • For HACS: custom_components/button_builder/
   • Verify __init__.py exists in that folder

4. Check logs for errors

   • Settings System Logs
   • Filter by "button_builder"
   • Look for registration errors

5. Verify manifest.json

   • Check custom_components/button_builder/manifest.json exists
   • Ensure valid JSON format

---

HACS Installation Failed

Symptoms:

• Download fails in HACS
• Repository not found

Solutions:

1. Check HACS is up to date

   • HACS menu About
   • Update HACS if available

2. Add repository manually

   • HACS Integrations Custom repositories
   • Add: https://github.com/[owner]/button-builder
   • Category: Integration

3. Check network connectivity

   • HA needs internet access to GitHub
   • Check firewall/proxy settings

---

Panel Shows Blank/White

Symptoms:

• Sidebar entry appears but page is blank
• White or empty page in iframe

Solutions:

1. Browser console errors

   • F12 Console tab
   • Look for JavaScript errors
   • Report errors in GitHub issues

2. Cache issues

   • Clear browser cache completely
   • Try incognito/private window

3. Check www folder

   • Verify custom_components/button_builder/www/ contains files
   • Should have panel.html, index.js, etc.

---

Configuration Issues

Colors Not Applying

Symptoms:

• Changed color but button doesn't update
• Button shows wrong color

Solutions:

1. Check state colors

   • State ON/OFF colors override background
   • Clear state colors if not needed
   • Or use Color Type = "blank-card"

2. Check gradient settings

   • Gradients override background color
   • Disable gradient if using solid color

3. Extra styles override

   • Check if custom CSS has background set
   • Extra styles take priority

4. Template overriding

   • Color templates override static colors
   • Check Advanced Templates

---

Preview Not Matching Dashboard

Symptoms:

• Button looks different in actual dashboard
• Colors or sizes don't match

Possible Causes:

1. Theme differences

   • Preview uses default styling
   • Dashboard may have custom theme
   • Theme CSS variables affect button

2. Card size context

   • Preview shows at fixed size
   • Dashboard grid affects actual size
   • Use aspect ratio for consistency

3. Entity state differences

   • Preview uses simulated state
   • Real entity may have different attributes
   • Especially affects auto-color features

---

YAML Syntax Errors

Symptoms:

• Copied YAML doesn't work in dashboard
• Card shows error message

Solutions:

1. Check YAML formatting

   • Use a YAML validator
   • Watch for tab vs space issues
   • Ensure proper indentation

2. Quote special characters `yaml

   Wrong

   name: Light & Lamp

   Correct

   name: "Light & Lamp" `

3. Escape template strings

   • Templates need proper quoting
   • Use | for multi-line strings

---

Performance Issues

Slow/Laggy Interface

Symptoms:

• UI feels sluggish
• Preview updates slowly
• Typing is delayed

Solutions:

1. Reduce animation complexity

   • Disable animations while editing
   • Heavy shadows impact performance

2. Browser resources

   • Close unused tabs
   • Check available memory
   • Try different browser

3. HA connection issues

   • Check HA performance
   • Network latency affects entity loading

---

Entity List Not Loading

Symptoms:

• Entity dropdown is empty
• "Loading entities..." never completes
• Entity search not working

Solutions:

1. Check HA connection

   • Verify you're logged into HA
   • Check browser console for errors
   • Authentication may have expired

2. Wait for loading

   • Large installations take longer
   • First load after restart is slower

3. iOS Safari issues

   • Known issue with entity loading
   • Try refreshing the page
   • Update to latest version

---

Browser-Specific Issues

Safari/iOS Issues

Known Issues:

• Entity list loading delays
• Backdrop blur may not render
• Copy to clipboard may fail

Workarounds:

• Use Chrome/Firefox if possible
• Manually copy YAML from output
• Refresh page if entities don't load

Firefox Issues

Known Issues:

• Some CSS effects may differ
• Backdrop-filter requires flags

Solutions:

• Enable layout.css.backdrop-filter.enabled in about:config
• Or avoid glass effects for Firefox users

---

Common Error Messages

"Entity not found"

Cause: Selected entity doesn't exist in HA

Solutions:

• Check entity ID spelling
• Entity may have been renamed
• Verify entity exists in Developer Tools States

"Invalid template"

Cause: JavaScript syntax error in template

Solutions:

• Check for missing brackets/quotes
• Use console.log for debugging
• Simplify template and rebuild

"Failed to load panel"

Cause: Panel resources not accessible

Solutions:

• Restart HA
• Clear browser cache
• Check www folder contents
• Verify file permissions

---

Getting Help

Before Reporting an Issue

1. Update to latest version

   • Many issues fixed in updates
   • Check HACS for available updates

2. Check existing issues

   • GitHub Issues page
   • May already be reported/resolved

3. Gather information

   • Button Builder version
   • Home Assistant version
   • Browser and version
   • Error messages from console
   • Steps to reproduce

Reporting Issues

Open an issue on GitHub with:

• Clear description of problem
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if visual issue
• Browser console errors
• HA logs if relevant

Community Support

• Home Assistant Community Forums
• Reddit r/homeassistant
• Discord HA server

---

Reset and Recovery

Reset Button Builder

1. Clear localStorage

   • F12 Application Local Storage
   • Delete button-builder-config key
   • Refresh page

2. Reset to defaults

   • Navigate to any preset
   • All settings reset to preset values

Recover Lost Configuration

• Configuration stored in browser localStorage
• Not synced between browsers/devices
• Copy YAML frequently to save work
• Consider saving favorite configs externally

---

Next Steps

• Getting Started - Basic setup
• FAQ - Frequently asked questions
• GitHub Issues - Report bugs