Skip to content

openHAB Sitemap Not Loading — Complete Guide

DodaTech Updated 2026-06-24 3 min read

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

  1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
  2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
  3. Misunderstanding that String is [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

What is the difference between Basic UI and Main UI?

Basic UI uses sitemaps (XML-like text files) for rendering. Main UI uses the openHAB REST API with a modern JavaScript interface and does not require sitemap files. Use Main UI for new installations.

Can I have multiple sitemaps?

Yes — create multiple .sitemap files in /etc/openhab/sitemaps/. Users can switch between them via the Basic UI URL parameter ?sitemap=name.

Why does my sitemap work on desktop but not on mobile?

Sitemaps are responsive by default, but complex Frame nesting can break on small screens. Simplify the hierarchy or use separate mobile and desktop sitemaps with label and icon adjustments.


DodaTech — sitemaps that load and display perfectly.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro