Troubleshooting

weewx-celestial manual · weewx-celestial on GitHub · Report an issue

Find the symptom. Almost every problem here is wiring rather than astronomy, and the page’s badge names most of them itself — see Reading the page for what each badge state means. In any state but LIVE the page stands as the report drew it, or where the last packet left it — the countdown chips and rosters advance only with loop packets — so a page that is entirely still is telling you to read the badge.

There is no page at `celestial/`

The HTML is generated by the normal WeeWX report cycle, typically every five minutes. Wait one cycle after installing and restarting.

If it still isn’t there, check that the report is enabled ([StdReport] [[CelestialReport]] enable = true) and look in the weewxd log for a generation error from CelestialReport. A template failure is only ever logged — the report cycle carries on and weectl report run still exits reporting success — so the log is the place to look, not the console.

On WeeWX 5.2, upgrade to 8.1.2 or later. Versions 7.2 through 8.1.1 cannot generate this page at all on WeeWX 5.2: they read body names from the report’s [Almanac] section, which WeeWX only began providing in 5.3. The log shows Ignoring template index.html.tmpl above a traceback ending in KeyError: 'Texts' (with PyEphem installed) or cannot find 'texts' (without it). 8.1.2 falls back to English body names there and the page generates normally.

The badge says `NO DATA (HTTP 404) — check loop_data_file`

The page found your web server but not the loop-data file. This is the single most common problem, and it is a path mismatch between two extensions:

The skin fetches loop_data_file, default ../loop-data.txt — relative to this report’s HTML_ROOT.
weewx-loopdata writes to [[FileSpec]] loop_data_dir, relative to its target report’s HTML_ROOT.

Make the two meet: either set loop_data_dir = .. on loopdata’s side, or point loop_data_file at wherever loopdata already writes. Then confirm the web server actually serves it:

curl -sI http://localhost/loop-data.txt | head -1

A file on disk that no URL reaches is the classic failure — loopdata writing into /dev/shm with no alias is the usual version of it.

If your pages live on a remote web server, loop-data.txt has to reach it at loop cadence, not archive cadence. weewx-loopdata can rsync it on every packet; see its manual. A stale file on the far end shows up here as a badge age that climbs and resets, never reaching LIVE.

The badge says `OFFLINE`, or `BAD DATA`

OFFLINE means the fetch itself failed — the browser could not reach the server at all. Check that the web server is up and, if the page is served over HTTPS, that the loop-data URL is too: a mixed-content block looks exactly like an outage.

BAD DATA means the file was served but could not be parsed as json. Look at it directly (head -c 300 loop-data.txt). A truncated or half-written file usually means something other than loopdata is writing there.

It also means a file that parsed but carried no current.dateTime.raw. The page times everything by the station’s own clock, which that field carries, so a record without it is ignored whole and the browser console says so. The fields line in Fields reference always includes it — check that yours has not been trimmed.

The badge age keeps climbing

The page is fine; the feed stopped. In order: is weewxd running, is weewx-loopdata still configured and enabled, and is the file’s modification time advancing?

ls -l --time-style=full-iso /home/weewx/gauge-data/loop-data.txt   # your loop_data_dir

If the timestamp is advancing but the page’s age is not resetting, the browser is being served a cached copy — check for a caching proxy between you and the file.

The badge says `CLICK-ME`

Working as designed: the page stops polling after expiration_time hours so an unattended browser does not poll for ever. Click to resume, or raise expiration_time. Appending ?pageUpdate=<page_update_pwd> to the URL disables expiration for that view — the password is visible in the page source, so treat it as a convenience, not a secret.

The star field is frozen

The dome’s stars and constellation figures come from backdrops the station regenerates every report cycle; the open page refetches one a minute (see How it stays live). When those stop arriving the page keeps the last good sky, and from 8.3.1 it also stops nudging the marks over it — a frozen dome is honestly old, while live marks crossing a motionless star field draw a sky that never existed — and posts a line under the panel:

Star field frozen — this sky is from 14:05 (reason) · what to check

The reason is the last refetch’s outcome, and it says where to look:

The line says	What it means	What to check
`no newer backdrop has arrived`	The fetches are succeeding; the file they return is old	The station: is the report still running each archive interval? Are `dome-svg*.txt` mtimes moving? Is a fragment template failing? (see below)
`dome-svg-3.txt returns HTTP 404` (or another status, and whichever fragment was asked for)	That fragment is not being served next to the page	Whether the files exist in `HTML_ROOT`, and whether whatever publishes your site (rsync, FTP) carries `.txt` as well as `.html`. The named file is the one that failed — a deploy that dropped only the numbered fragments leaves `dome-svg.txt` itself serving perfectly
`dome-svg-3.txt is not a sky fragment`	Something answers, but it is not SVG	A web server returning an error page with status 200
`dome-svg.txt is empty`	The file is there and has nothing in it	If it names a numbered slot, the page is asking for a slot beyond the current archive interval — harmless, and it corrects itself on the next cycle. If it names `dome-svg.txt` itself, the station is writing no backdrop at all: check that weewx-skyfield is serving the report (the dome would show an install hint), and that a report cycle has run since the last restart. Before 8.3.2 a station with a non-default `group_interval` emptied every fragment — upgrade if you are on anything earlier
`no response for dome-svg-3.txt`	The request failed, or hung until it timed out	The network between browser and server; a page left open through a server restart
`dome-svg.txt is stamped ahead of the station's clock`	The station answered, and the sky it sent depicts a time the station’s own loop packets have not reached	The clock that stamps your archive records against the one weewxd runs on — see below. Nothing is wrong with the report: it is generating backdrops perfectly, and the page is refusing them because it will not draw a sky from the future

Two things this is not. The LIVE badge is a different instrument: it watches loop_data_file, which is usually a different URL in a different directory, so a healthy badge says nothing about the fragments (and a frozen star field says nothing about your loop data). And a dead loop feed does not raise this line at all — the backdrop’s age is measured against the station’s clock, which the loop packets carry, so that the viewer’s own clock can never freeze a healthy sky; when the feed stops, or never started, the badge is the fault to read, and the dome’s marks stop by themselves.

If it says `no newer backdrop has arrived` and the files are being written

On the station:

# Are the fragments being rewritten each report cycle?  Run twice, a
# cycle apart -- the timestamps should move.
ls -l <HTML_ROOT>/celestial/dome-svg*.txt

# Did a fragment template fail?  They deliberately carry no error
# catcher, so a failure is logged and the PREVIOUS file is left in
# place -- which looks exactly like a frozen sky.
sudo journalctl -u weewx | grep -i dome

If you set report_timing on this report, this is the line you will see. The Celestial skin does not support a report_timing that makes its reports run less often than the archive interval — see Report timing is not supported. The backdrops are written by the report cycle, so a report throttled to run hourly on a five-minute archive leaves the page holding a backdrop up to an hour old, which is past the staleness limit: the dome freezes and this line stands, permanently. Nothing is broken; the page simply cannot tell a deliberately slow report apart from a station that has stopped. Remove the report_timing line and the dome runs normally again. Nothing needs configuring, and the dome resumes stepping as soon as a backdrop lands.

If it says `stamped ahead of the station's clock`

Check your station’s clock — specifically, whether the clock that stamps your archive records agrees with the one weewxd is running on.

The page works out which backdrop it wants from the time your loop packets carry, and it refuses any backdrop depicting a time your station has not reached yet — that refusal is what stops it drawing a sky from the future. If a hardware console’s clock runs fast, its archive records are stamped ahead of the loop packets, so every backdrop looks like the future to the page and is refused. Ahead by more than one archive interval, none is ever accepted, and after three cycles the dome freezes.

This is a misconfigured station rather than a fault in the page, and it is worth fixing on its own account: every archive record you are storing carries the same wrong time. WeeWX checks a Vantage console’s clock periodically and logs the result:

grep "Clock error" /var/log/syslog | tail

A healthy station reads a second or two. Anything approaching a minute deserves attention; more than one archive interval will freeze the dome as described.

The line names this case as its own from 8.3.6. Earlier versions marked the fetch healthy before refusing the answer, so the panel read no newer backdrop has arrived — which sent readers looking for a report cycle that was running the whole time.

A panel shows an install hint instead of a chart

The almanac WeeWX has registered cannot serve that panel. The page degrades on purpose rather than failing:

What you see	What it means
The Geocentric shows a hint	Neither weewx-skyfield nor PyEphem is registered — the built-in almanac serves none of the positions the Celestial page needs
The dome shows a hint	weewx-skyfield is not installed or not registered
The dome draws, but no satellites	weewx-skyfield is older than 2.0, or no `[Skyfield] [[Satellites]]` are configured
No comets on the dial	weewx-skyfield is older than 2.1, or no `[[Comets]]` are configured
The Proxima Centauri row is empty	PyEphem is serving the page; its star catalog lacks Proxima

The full table is under the almanac tiers. The page’s footer always names the almanac that actually computed it, which is the quickest way to confirm which tier you are on.

A countdown chip never appears

Three different causes, in the order worth checking:

Its field is not on the fields line. Check loop-data.txt for the key (see the verification commands in Installation), and compare against the Fields reference.
The almanac cannot compute it. weewx-skyfield 2.1 is what serves the meteor shower and supermoon chips; older versions simply omit them, one log line per field at startup.
The event is more than 30 days out. The equinox/solstice, perihelion/aphelion, supermoon, eclipse and comet-perihelion chips are windowed guests by design.

A satellite row says `no usable orbital elements`

weewx-skyfield could not fetch or parse that satellite’s elements, or the cached ones have expired. Check the weewxd log around startup for the CelesTrak fetch, confirm the NORAD number is right (search CelesTrak), and give it a restart — elements are fetched shortly after start and refreshed every few hours.

A satellite is configured but never has a pass

Check its inclination against your latitude. A satellite’s orbital inclination bounds the latitudes it can ever appear over; one that never crosses your sky will honestly report no passes for ever. The roster is not broken — it is telling you the truth.

Also worth knowing: most passes are not visible passes. The “next pass overhead” roster counts every pass; the Next Visible Pass panel only counts the ones where the satellite is sunlit against a dark enough sky.

A comet’s row and diamond are empty

The Minor Planet Center dropped that comet from its element file — faded comets are removed routinely. The page renders honest absence rather than a fabricated position. Remove it with --remove-comet if you don’t expect it back, or leave it: it will return if the MPC republishes elements.

`theme = light` and the page is still dark

Three things to check, in this order:

Where the option sits. theme is a report option, beside lang — not inside [[[Extras]]]. In [[[Extras]]] it is simply ignored.
Whether the report has regenerated. The plate is baked in at generation time (there is nothing in the browser to switch), so the change appears on the next report cycle. Reload after that; if the page still looks dark, reload once more — the stylesheet is version-tagged, but a proxy may hold the old page itself.
Whether weewx-skyfield is installed. The light plate is the paper the sky dome and Next Visible Pass chart are drawn on, and those come from weewx-skyfield. Without it the page has no charts to match and stays dark whatever the option says — the same tier where the panels show an install hint.

Case does not matter (theme = Light is light), but a value that is not one of the three (theme = paper, theme = white) leaves the page dark rather than failing the report — a page that generates in the wrong plate beats a page that does not generate — and says so in the log:

WARNING user.celestial: The Celestial report has an unusable theme option;
rendering the dark plate.  Valid values are dark, light and auto.

The page looks unstyled — the dial is solid black discs

celestial.css did not reach the browser. The stylesheet is deployed by WeeWX’s CopyGenerator, which re-copies it on the report’s first run after a restart, and the page version-tags the URL so browsers refetch it. So: restart weewxd, then reload the page. If it persists, confirm celestial.css exists in the report’s HTML_ROOT and is served (a 404 on it produces exactly this look).

weewxd will not start after upgrading

Look for this in the log, and remove the entry it names:

[Engine] [[Services]]
    data_services = ..., user.celestial.Celestial

That registration is a leftover from 2.x. 6.x tolerated it with a stub; 7.0 deleted the stub, so a stale entry now stops the engine. Removing it is the whole fix — this extension has run no service since 6.0.

Values never tick, and there are no motion trails

Rates need two loop packets. For the first refresh_rate seconds after a page load nothing moves, by design. If it never starts moving, the feed is delivering the same packet repeatedly — check that refresh_rate matches loopdata’s write cadence (2 seconds for the Vantage driver) rather than being much shorter than it.

The countdown chips and the satellite rosters are not this symptom: they advance on each loop packet — every refresh_rate seconds, not every second — by design.

Times are in the wrong zone

By default the page shows the station’s timezone, auto-detected at report time, so remote viewers see station time. Override with time_zone in the skin’s [Extras]: an IANA name forces that zone, browser uses the viewer’s own. See Configuration.

The translation did not take

Four separate things can be meant by this:

Nothing changed at all. lang takes effect when the page is next generated, not on the next loop packet. Wait a report cycle.
Everything translated except the body names. [Almanac] display names — the bodies, and the satellites and comets — need WeeWX 5.3 or later; 5.2 never hands that section to the almanac. The rest of the page translates normally and the bodies read Moon, Jupiter, Proxima. See Translations.
Labels translated, live values did not. Loop-data values follow loopdata’s target report, not this one — one language per loopdata instance. See Translations.
My edits vanished after an upgrade. weectl extension install overwrites skins/Celestial/, including its lang/ files. Put local overrides in weewx.conf as [[[Texts]]]/[[[Almanac]]] entries under the report or [[Defaults]], where they survive and are merged over the shipped files.

Nothing here matches

Two commands worth having before asking for help — what the feed actually carries, and what the log said:

# the paths below are examples -- use your own loop_data_dir
python3 -c "import json; d=json.load(open('/home/weewx/gauge-data/loop-data.txt')); print(sorted(k for k in d if k.startswith('almanac')))"
grep -i -e celestial -e loopdata -e skyfield /var/log/syslog | tail -40
# or, where journald has replaced the syslog file:
journalctl -u weewx --no-pager | grep -i -e celestial -e loopdata -e skyfield | tail -40

That second command answers the version question too: from 8.3.1 the skin announces itself at the first report that renders the page after a restart —

INFO user.celestial_sky: Celestial version is 8.3.1.

— and it is the version of the skin that actually rendered the page, which is the one worth reporting. It is logged once, not every cycle, so look near the restart rather than at the tail of the log; it speaks again only if the version changes, which is how a later upgrade announces itself without a restart. Installing over a running weewxd never changes the code weewxd has already imported, so the line that follows an install is the one after your restart. (Before 8.3.1 this extension had no service and never named itself at all; weectl extension list is the fallback.)

Then open an issue with both, your WeeWX version, and the versions of weewx-celestial, weewx-loopdata and weewx-skyfield.