Skip to content

Troubleshooting

Jump to bottom
Fischer, Fabian edited this page Apr 28, 2026 · 1 revision

Troubleshooting

Common Issues

"Forbidden — check API location settings" (403)

Cause: Your API key is valid, but the coordinates you entered don't match a configured API location on kachelmannwetter.com.

Fix:

  1. Log in to accounts.meteologix.com
  2. Go to your subscription → "API-Standorte verwalten"
  3. Make sure the coordinates match what you entered in Home Assistant
  4. The hobby plan allows max 2 locations

"Invalid API key" (401)

Cause: The API key is wrong or expired.

Fix:

  1. Check your API key in account settings → "API-Keys verwalten"
  2. If it expired, generate a new one
  3. Use the reauth flow in HA (notification will appear automatically)

"Rate limit exceeded" (429)

Cause: You've used all your daily API requests.

Fix:

  1. Increase the update interval: Settings → Devices & Services → KachelmannWetter → Configure
  2. Recommended: 900 seconds (15 min) or higher
  3. The integration will automatically retry after the rate limit resets
  4. See API & Rate Limits for detailed calculations

Entities show "unavailable"

Possible causes:

  • API is temporarily down → wait for next update cycle
  • Network issue → check your internet connection
  • Rate limited → check sensor.kachelmannwetter_api_requests_remaining
  • API key expired → check for reauth notification

Debug:

  1. Enable debug logging (see below)
  2. Check Home Assistant logs for error messages
  3. Try the diagnostics download

Weather condition shows wrong icon

Cause: The Kachelmann API uses different weather symbol names than HA expects.

Info: All known symbols are mapped. If you find an unmapped one, please open an issue with the weatherSymbol value from diagnostics.

Forecast shows wrong precipitation probability

Info: Precipitation probability comes from the 14-day trend endpoint (not the 6h forecast). It represents the probability of ≥1mm precipitation for the entire day, not per hour.

Entities missing after update to v2.x

Cause: v2.0.0 changed the device identifier from config entry ID to coordinates.

Fix: Remove the integration and re-add it. Your automations will reconnect automatically if entity IDs haven't changed.

Debug Logging

Add this to your configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.kachelmannwetter: debug

Then restart Home Assistant. Debug logs will show:

  • When data updates are triggered
  • API endpoint types being called
  • Rate limit information
  • Any errors during fetching

Note: Since v2.3.1, coordinates and full URLs are no longer logged for privacy.

Diagnostics

Download diagnostics for bug reports:

  1. Go to Settings → Devices & Services → KachelmannWetter
  2. Click the three dots menu → Download diagnostics
  3. The download contains all coordinator data with the API key automatically redacted

Attach this file when opening issues.

Checking API Coverage

Run the audit script to verify all API fields are mapped:

cd /path/to/haKachelmannWetter
python scripts/audit_api_coverage.py

Getting Help

  1. Check this wiki first
  2. Search existing issues
  3. If unresolved, open a new issue with:
    • Your HA version
    • Integration version (from manifest.json)
    • Diagnostics download
    • Relevant log entries

Clone this wiki locally