Troubleshooting

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

Start here: is the Skyfield almanac actually registered? Nearly every “my values didn’t change” report answers itself at this line. Restart WeeWX and look in the log for:

Skyfield almanac registered; reports will use Skyfield for almanac computations.

If that line is present, this extension is answering your $almanac tags. If it is absent, one of the startup messages below says why.

Symptoms

The Sky page never appeared

It lands at <HTML_ROOT>/skyfield/index.html after the first report cycle — not immediately on restart. If it is still missing:

Check enable in the [[SkyfieldReport]] stanza under [StdReport].
Check where it actually went. If you see public_html/public_html/skyfield, HTML_ROOT in that stanza was written as an absolute-looking path; it must stay relative.
Look for a Cheetah error in the log naming index.html.tmpl.

Some `$sky_page` panels are empty

The page renders but some panels are blank. This extension’s almanac is not registered, so the panels have nothing to draw from — the panels and the almanac install and configure separately, and a skin can call $sky_page on a station that never enabled [Skyfield]. The more of the almanac is missing, the more panels go blank: without this extension the dome, the pass chart, the satellite rows, the equation of time and the moon’s apsides always decline, and on a station without PyEphem either, almost every panel does.

Two things confirm it. The page’s footer credit reads Computed with the station’s built-in almanac, and weewxd’s log carries one warning on the first report cycle after a restart — the Skyfield almanac is not registered, so $sky_page cannot draw the sky, or WeeWX is computing $almanac with its own sunrise/sunset formulas where PyEphem is absent too.

Either way, to fill the panels in, make sure user.wxskyfield.WxSkyfield is in data_services and that weewx.conf has a [Skyfield] section with enable = true; installing this extension does both. Then restart WeeWX and look for the Skyfield almanac registered line. If you would rather the page simply not reserve space for the panels, gate them in the template on $sky_page.can_draw() — see Panels in your own skin.

My almanac values didn’t change after installing

If the registration line is in the log, they did change — but the two almanacs agree closely for common tags, so sunrise moving by a few seconds is easy to miss. Compare something with a real difference: a twilight tag with a custom horizon ($almanac(horizon=-6).sun(use_center=1).rise) differs from PyEphem by two to three minutes, because this extension follows the USNO’s geometric definition. See Accuracy and conventions.

Satellite times now show a date

Intended, as of 2.5. A pass is searched up to a week ahead, so a bare clock time for a pass three days out read as tonight. The six satellite times — rise, culmination and set on next_pass and next_visible_pass, and the satellite’s own rise, transit and set — now render in the ephem_year context, with their date, rather than ephem_day. For the old look on one tag, format it in place: $almanac.iss.next_visible_pass.rise.format(format_string="%X"). Overriding ephem_year itself would also restyle the equinoxes, the moon-phase finders, meteor-shower peaks and a comet’s perihelion. Values and .raw are unchanged. See How far away a time can be.

One body reads `N/A` for everything

Expected, and the diagnosis is built in. A satellite whose elements are missing or more than seven days old collapses every tag to N/A rather than reporting confidently wrong pass times; a comet the MPC has dropped from CometEls.txt does the same. Two tags stay live precisely so you can see why:

$almanac.iss.elements_epoch      ## when the elements were issued
$almanac.iss.elements_age        ## how old they are now

The log names it once per crossing — see element messages. If the age keeps growing, the fetch is failing: check network access to CelesTrak or the Minor Planet Center, and confirm satellite_downloads / comet_downloads are not false.

A satellite never has a visible pass

Often the truth rather than a fault. A satellite’s orbital inclination bounds the latitudes it can appear over: Hubble, inclined 28.5°, never climbs usefully above the horizon for stations poleward of about ±35°. The configured defaults — ISS at 51.6° and Tiangong at 41.5° — put on a show for essentially everyone. See Choosing satellites.

Remember also that next_visible_pass is deliberately strict: sunlit, against a sky with the sun below −6°, peaking at least 10° up. next_pass is the unfiltered fact and will often have an answer when next_visible_pass does not.

A number looks wrong by a factor of 3600 or 57.3

A units problem, not an astronomy problem, and Values, units and types diagnoses it — most often an unpinned .raw read on a duration.

A page stopped updating after I changed a `$sky_page` call

A mistake in a $sky_page argument is a template error, not a blank panel, so it is caught while you are editing rather than months later. WeeWX skips the whole page and leaves the previous copy on disk, which is why it looks stale rather than broken, and logs Evaluation of template … failed with exception '<class 'user.wxskyfield_sky.SkyPageUsageError'>' followed by a **** Reason: line naming what is wrong. The usual causes: a label_scale that is not a positive number, a narrow value that is neither true nor false, or a label_layers entry that is not a (scale, media_query) pair, repeats a scale, or has a query using anything but letters, digits, spaces and : ( ) , . - with its parentheses balanced — for example label_layers media query '(width < 600px)' is not usable: … for example '(max-width: 600px)'. The range syntax (width < 600px) is always refused, because the query is written inside inline SVG, where < is markup. An unknown palette or theme name fails the same way. See Panels in your own skin.

A tag reports an error instead of a value

Per-tag errors are by design: they appear in place without taking down the page. The exception is a mistake in a $sky_page argument, which fails the whole page so you notice it — see A page stopped updating after I changed a $sky_page call. The usual causes are asking a body for something outside its surface (a satellite has no .phase; Mars has no .next_pass), or an almanac time outside the bundled ephemeris’s span (mid-1899 to 2053). Satellite and comet tags never fall through to PyEphem, so an unrecognized attribute on one is always a clean error rather than a mysterious PyEphem value.

One version-specific cause is fixed in 2.1.3: before it, on WeeWX 5.2 only, every display name — $almanac.<body>.label, .constellation.label and $almanac.next_meteor_shower.label — raised instead of answering, and the Sky page, which uses them, failed with them. Upgrading weewx-skyfield fixes it on 5.2; the names themselves still need WeeWX 5.3, and stay English and Latin below it.

Reports got slower

The first report cycle after a restart, and the first after local midnight, pay full uncached cost while the day’s entries repopulate; the cycles after them run warm. If it is slow every cycle, the Sky page is the busiest page here, and Performance explains what costs what and which options move the needle — star_mag_limit, constellation_lines, report_timing, or enable = false on the page while keeping every tag. In your own skin, each extra label_layers entry adds one more label layout per chart per cycle.

Install messages

Printed by weectl extension install, not logged. The install fetches the first satellite and comet orbital elements so their tags work from the first report cycle, which is what it is doing when it pauses.

Message	Meaning
`Fetching satellite orbital elements for … from CelesTrak…` / `Fetching comet orbital elements from the Minor Planet Center…`	Normal, and why the install pauses. The comet file is the slower one.
`Satellite elements for … are current; not fetching.` / `Comet elements in … are current; not fetching.`	Nothing to do: what is cached is younger than the interval weewxd refreshes on. Usual on an upgrade.
`CelesTrak has no current elements for X (N) -- check the NORAD number…`	A typo in `[[Satellites]]`, or an object that has decayed. Retrying cannot fix it: correct or remove the entry. See Satellites.
`Could not fetch elements for X now (…); weewxd asks CelesTrak again when it starts.`	A network or CelesTrak problem, and true as stated: weewxd fetches missing elements at startup and about every three hours after. The satellites after X are not asked for (`not asking for … either`), as CelesTrak’s usage policy requires.
`Skipping satellite X: '…' is not a NORAD catalog number.`	The value in `[[Satellites]]` is not a number. weewxd logs its own version of this at startup.
`Skipping satellite X: SGP4, which computes satellite positions, takes catalog numbers from 1 to 339999.`	The number is past what SGP4 can take, or zero. weewxd refuses it at startup too.
`weewx-skyfield requires Skyfield 1.47 or later, found …` / `… which is not installed.`	The install stops before changing anything. Upgrade or install Skyfield — see Upgrading Skyfield — and run the install again.
`Not fetching satellite elements: satellites need Skyfield 1.49 or later, found …`	Skyfield 1.47 or 1.48. Everything but the satellites works; they stop within 7 days. Upgrade Skyfield to keep them.

Startup messages

Message	Meaning
`Skyfield almanac registered; reports will use Skyfield…`	Working. This is the line to look for.
`WxSkyfield status: disabled...enable it in the Skyfield section of weewx.conf.`	`enable = false` in `[Skyfield]`.
`This version of WeeWX (…) does not support almanac extensions`	WeeWX older than 5.2. The extension declines gracefully and the built-in almanac stays in place.
`weewx-skyfield requires Skyfield 1.47 or later, found …`	Skyfield was downgraded after the install, which checks the same thing. Upgrade it — see Upgrading Skyfield. Debian 12 ships 1.45, which is too old.
`Satellites need Skyfield 1.49 or later, found …`	Skyfield 1.47 or 1.48, which cannot read the OMM format satellite elements are fetched in. Nothing is fetched, and satellite tags stop working within 7 days. Upgrade Skyfield.
`Could not load … The Skyfield almanac will not run.`	The ephemeris file could not be read. Reinstall the extension.
`Could not build the skyfield timescale…`	Skyfield could not initialize; usually a broken or partial Skyfield install.
`init: Could not load the Hipparcos star catalog: … Star support disabled.`	Everything except star tags keeps working.
`Loaded N stars to magnitude M from the full Hipparcos catalog.`	Normal: the dome’s star field.
`Ignoring unrecognized [Skyfield] option: …`	A typo, or a leftover from an older release — the pre-2.0 `stars` option lands here. See Configuration.
`Ignoring [Skyfield] [[Satellites]] entry …`	The tag name shadows a planet, star, `hip_` or `sat_` name, or the NORAD number is not a number, or is past 339999, the highest SGP4 takes.
`Ignoring [Skyfield] [[Comets]] entry …`	Same, for a comet’s name or designation.

Report messages

Logged while a page renders. All but the last are logged once per name per weewxd process rather than per call — so the line appears on the first report cycle after a restart and not again. Restart WeeWX to see whether a fix took.

Message	Meaning
`palette 'classic-…' was dropped in 2.3 and is being drawn as …`	A template still passes a `classic-` palette to a `$sky_page` panel. It renders as the plate that replaced it; change the name to `night` or `light` — see Panels in your own skin.
`theme 'classic-…' was dropped in 2.3 and is being drawn as …`	The same name in a report’s `theme` option, which takes `dark`, `light` or `auto`. It renders as `dark` or `light`; set one of those instead.
`the Skyfield almanac is not registered, so $sky_page cannot draw the sky…`	A skin uses the `$sky_page` panels on a station where the almanac service is not running, so the five panels that need it render empty. See Some `$sky_page` panels are empty.
`WeeWX is computing $almanac with its own sunrise/sunset formulas…`	The same, on a station without PyEphem either, so almost every panel renders empty. Same section.
`sky_page.<panel> failed (<Error>: …); rendering that panel blank.`	A panel hit an unexpected error while computing. Only that panel is blank; the rest of the page renders. Logged every time it happens — please report it with the lines around it.

Element messages

Message	Meaning
`Fetched satellite elements for N.` / `Fetched comet elements into …`	A refresh succeeded.
`Deleted …/wxskyfield_sat_N.tle, superseded by …/wxskyfield_sat_N.csv.`	Once per satellite after upgrading to 2.10: the first fetch in the new format replaced the TLE an older release cached.
`Could not delete …/wxskyfield_sat_N.tle, which the fetched …/wxskyfield_sat_N.csv supersedes: …`	Usually permissions. Harmless — the fresher CSV is used — but delete the file by hand.
`satellite_elements: could not load …: …`	A cached or supplied element file is not elements for that satellite. A broken file costs only itself: the satellite’s other file, if there is one, still serves.
`Could not fetch satellite elements for N (…). Asking CelesTrak nothing more until the next round, in 3 hours, for every satellite; …`	A fetch failed, and what came back is quoted: a status with the server’s own words, or the failure itself (a timeout, a refused connection, an answer that was not elements). Every cached file is kept and no satellite is asked for again for three hours, as CelesTrak’s usage policy requires. A 403 or 429 means this address is asking too often — usually several installs behind one address, each asking; let one fetch and copy the files to the rest with `satellite_downloads = false`. A 5xx means CelesTrak is under load. A 301 means the URL is outdated: update the extension. Restarting weewxd asks again at once.
`CelesTrak has no elements for satellite N (HTTP 404 …); check the NORAD number. Not asking for it again until weewxd restarts; …`	A catalog number CelesTrak does not carry: a typo in `[[Satellites]]`, or an object that has decayed. The other satellites are still fetched. Fix the number and restart.
`Could not fetch the comet elements from the MPC (…). Asking again in 2 days; …`	Any failure, whatever came back: the cached file, if there is one, is kept and the fetch waits the full two days before trying again.
`Satellite N has no usable elements (missing, unreadable, …)`	Every tag for that satellite now reads `N/A`. Logged once at the crossing, not per tag.
`Satellite N has usable elements again.`	Recovered.
`Comet X (…) has no elements in the cached CometEls…`	The MPC dropped it, or the cache is missing. Tags read `N/A`.
`Comet X (…) has elements again.`	Recovered.

Known Skyfield issues

Issues in the underlying Skyfield library that you might notice. None require action. An entry stays here while any Skyfield this extension supports is still affected, and is removed once the oldest supported release carries the fix.

A rare `RuntimeWarning` from `almanac.py` line 339

Very occasionally, report generation prints this — in the console when running reports by hand, or in the log of a running WeeWX (at most once per start, since Python deduplicates warnings):

skyfield/almanac.py:339: RuntimeWarning: invalid value encountered in divide
  return - 2*c / (b + sign * sqrt(discriminant))

This is an upstream Skyfield bug, tracked as skyfield issue #1114, and it affects Skyfield releases through 1.54. The final refinement step of Skyfield’s rise/set solver fits a parabola through its last two altitude samples; when the solver’s iteration happens to land, to the last floating-point bit, exactly on the horizon, that fit degenerates to a 0/0 division. It is a pure floating-point coincidence: it can strike any body, any latitude and any date, and the affected dates even differ between operating systems, NumPy versions and CPU math libraries. Inside Skyfield, the affected event’s time becomes NaN.

weewx-skyfield already contains the failure: it discards any event time that is not a finite time within the day being searched, so the worst possible outcome is a single rise or set tag coming up empty for a while — and in practice pages render complete. No configuration change, downgrade or workaround is needed.

weewx-skyfield’s author diagnosed the root cause — with a deterministic reproduction — in issue #1114 and submitted pull request #1140 with the fix and a regression test. Skyfield merged the fix on August 4, 2026, closing the issue, and shipped it in Skyfield 1.55 on August 7, 2026 — upgrading to Skyfield 1.55 or later makes the warning disappear. Upgrading is routine — see Upgrading Skyfield.

Still stuck

Open an issue on the weewx-skyfield GitHub project with your WeeWX version, your Skyfield version (python -c 'import skyfield; print(skyfield.__version__)'), the [Skyfield] section of your weewx.conf, and the startup lines from your log.