openHAB Sitemap Not Loading — Complete Guide
In this tutorial, you'll learn about openhab sitemap not loading. We cover key concepts, practical examples, and best practices.
Hook
You open the openHAB web UI or Basic UI app. It says "Loading..." or shows an empty page. The backend is running (you can check via SSH), but no sitemap appears. The interface your family uses to control the house is blank.
The Wrong Way
Deleting the entire sitemaps folder and starting from scratch loses all your carefully-designed pages, labels, and groupings.
# BAD: Deleting all sitemaps
rm -rf /etc/openhab/sitemaps/*
Basic UI: "No sitemap found"
All sitemaps gone — must recreate from scratch
You lose hours of layout work.
The Right Way
Check for sitemap file errors and fix them without deleting data.
# 1. Check which sitemaps are available
ls -la /etc/openhab/sitemaps/
default.sitemap
dashboard.sitemap
# 2. Check for syntax errors in the sitemap
tail -100 /var/log/openhab/openhab.log | grep -i "sitemap\|error\|parse"
2026-06-24 10:00:00.000 [ERROR] [ui.sitemap] - Error parsing sitemap 'default': Line 15: mismatched input 'Frame'
# 3. Fix the syntax error — open the sitemap file
# 4. Validate the sitemap structure
# Common issues: missing closing brackets, wrong keyword case
sitemap default label="Home" {
Frame label="Living Room" {
Switch item=Light_Switch
Text item=Temperature
}
}
# 5. Test with a minimal sitemap first
cat > /etc/openhab/sitemaps/test.sitemap << 'EOF'
sitemap test label="Test" {
Frame label="Test" {
Text item=System_Uptime
}
}
EOF
# 6. Access http://openhab:8080/basicui/app?sitemap=test
Test sitemap loads correctly
Then incrementally add your full sitemap content back.
Prevention
- Validate sitemap syntax with a linter before deploying.
- Keep a backup of your working sitemap in version control (git).
- Start with a minimal sitemap and add elements one at a time.
- Use the Main UI instead of Basic UI for new projects — it does not require sitemaps.
- Monitor openhab.log after every sitemap change.
Testing Your Fix
After applying the fix, run this verification to confirm everything works:
# Verify the tool is responding
command -v tool --version
Create a simple test script and run it. If the output matches your expectations, the fix is complete. If errors persist, review each step above -- the problem is often a missed configuration detail.
Common Mistakes with sitemap
- Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
- Non-exhaustive pattern matches that compile with warnings then crash at runtime
- Misunderstanding that
Stringis[Char]with poor performance for large text operations
These mistakes appear frequently in real-world OPENHAB code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.
Practice Exercise
Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.
This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.
FAQ
DodaTech — sitemaps that load and display perfectly.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro