Troubleshooting and FAQ

info

The window that start.bat opens shows useful status and error lines. Keep it open and check it when something misbehaves.

Connection & Sync Issues

Module backend unreachable

Means: The browser cannot reach the module server.

Fix:

1. Check that the start.bat window is still open and shows that the ZD Weather HTTP server is serving on port 5003.
2. If it closed or showed an error, run start.bat again and read the error.
3. Click Reload panel in the message, or reopen the module.
4. If you use a remote setup, confirm MODULE_SERVER_URL in .env points to your machine’s IP (not the Hub’s). See Install and Setup.

Engine Disconnected / Nothing goes on air

Means: The module reached Reality Hub, but the Show or Engine is not ready.

Fix:

1. Select Show, Rundown, Engines (at least one), and Template, then click Sync. All four are required.
2. Confirm the Show is started and the Engine is running in Reality Hub.
3. Click Sync again. You should see Engine Connected.

Not connected — select Show, Engines, Rundown & Template, then Connect & Sync

Means: This is the normal state until you complete Advanced setup and click Connect & Sync. The module asks for a fresh sync each session, even if a previous session was configured. Your playlist still restores on restart; only the connection status needs the fresh click.

Fix: Select Show, Engines, Rundown, and Template, then click Connect & Sync.

The Connect & Sync button looks dim even though everything is fine

Means: This is expected. After a successful sync, if nothing in Show, Rundown, Template, or Engines has changed, the button shows a quiet ✓ Synced look.

Fix: Nothing to do. Change any of those fields, or lose the Hub connection, and the button lights up again.

City Search & Forecast Data

City search shows "search unavailable"

Means: The module could not reach the geocoding service.

Fix:

1. Check that the module machine has internet access.
2. Try again in a moment.
3. If the machine is offline on purpose, use Random Fill (built-in city list), or add cities while temporarily online.

A city will not add, or a row shows STALE with "refresh failed"

Means: The forecast fetch for that city failed.

Fix:

• Click Refresh on the row to retry.
• Use Refresh All to retry every stale row.
• If one city keeps failing, remove it and add it again.

A row shows "partial"

Means: The weather service returned data for that city but was missing some fields. Those fields use default values.

Fix: Usually nothing. The graphic still airs. Refresh the row later to try for complete data.

Map Issues

The map is blank or shows an offline overlay

Means: Map tiles need internet, and there is none.

Fix:

• This is expected offline. Everything else still works; you just do not get the map.
• For a map on an offline or intranet machine, set WEATHER_TILE_URL in .env to your internal tile server, then restart the module.

Playout & Cycle Issues

The cycle stopped on its own with "playout failing"

Means: The module tried to fire graphics several times in a row and each attempt failed, so it stopped for safety.

Fix:

1. Check that the Engine and Show are still running in Reality Hub.
2. Look at the start.bat window for the underlying error.
3. When the Engine is healthy again, press Start to resume.

The graphic airs but a field is wrong or blank

Means: Usually a template mismatch — the data key the module sends does not match a field in the template.

Fix:

1. Confirm you selected the correct L_Weather_LT template in Advanced setup.
2. If someone edited the template, field keys may have changed. The module fields must match the template keys exactly. Hand this to whoever maintains the module or template.

Show / Rundown / Engine controls are greyed out

Means: A graphic is live. The cycle is running, or it was stopped but the last graphic is still on air (Stop leaves it up on purpose).

Fix:

1. Press Stop if the cycle is still running.
2. Press Out Graphic or Clear List to take the graphic off air. Stop alone does not unlock the controls.
3. The controls unlock when nothing is on air. The Weather template dropdown is never locked.

Playlist Issues

My playlist did not come back after a restart

Means: The saved state on disk was incomplete or could not be written.

Fix:

1. Make sure you clicked Sync with a full config at least once. An incomplete config is not rebuilt on boot.
2. Check the start.bat window for a line containing Persist failed:.
3. Confirm the module can write to its own folder.

After I switched Show or Rundown, my playlist vanished

Means: Changing Show or Rundown clears the playlist on purpose, so orphaned rundown items are not left on the old Show. You are asked to confirm first if cities were in the playlist. Changing Engine selection does not clear the playlist.

Fix: Rebuild the playlist for the new target, or switch back before syncing if the change was a mistake.

Setup & Deployment

What port does the module use?

5003. Each Custom Module runs its own small server. ZD Weather uses port 5003.

Can remote operators use it without installing anything?

Yes. If the module runs on the Hub machine, remote operators open the panel in Reality Hub. Their browser reaches it through the Hub proxy. They never connect to port 5003 directly.

What are the deployment setups?

There are two configurations:

• Co-located — the module runs on the same machine as the Hub. This covers a single workstation and starting the module on the Hub server. Use the defaults.
• Remote module — the module runs on your machine and the Hub is elsewhere. Set REALITY_HUB_HOST (the Hub) and MODULE_SERVER_URL (your own IP).

Does it work offline?

Partly. The module, UI, and saved playlist work offline. Live forecasts and map tiles need internet. For maps on an offline network, set WEATHER_TILE_URL to an intranet tile server. Forecasts need access to the weather service.

Is my Reality Hub API key safe in this module?

It lives only in your local .env, which you do not distribute. Treat it like a password. If it ends up in a shared file, rotate it in Reality Hub: issue a new key, revoke the old one, update .env, and restart the module.

Playlist & Playout Behavior

How many cities can I add?

The playlist has no hard limit. Random Fill adds 1–10 cities at a time from a pool of 199 cities across 53 countries.

Can I limit Random Fill to one country?

Yes. Pick a country from the dropdown above the Random Fill count. Leave All countries for a global sweep.

How long does each city stay on air?

Whatever you set — 6 to 120 seconds, default 6. You can change it mid-broadcast without losing your place.

How often do forecasts update?

Automatically every 45 minutes by default (adjustable 10–240). You can also refresh any row, or all rows, on demand.

Why does the cycle not restart automatically after a reboot?

For broadcast safety. Auto-firing graphics after an unexpected restart could put something on air you did not intend. Your playlist returns, but you press Start when you are ready. A banner reminds you if the cycle was running before.

What is the difference between Clear, Out, and Stop?

Control	Result
Stop	Pauses cycling. Whatever is on air stays on air.
Out	Takes graphics off air, but keeps the playlist.
Clear	Removes every city from the playlist (and its rundown items), and sweeps leftover L_Weather_LT rundown items from earlier sessions.