weatherfeeder/docs/troubleshooting.md

Troubleshooting

Use this guide with configuration and operations. Messages are emitted through the standard logger on stderr.

config load failed: ... read "config.yml"

Symptom: startup exits before building sources or sinks.

Likely cause: the process working directory does not contain config.yml, or the runtime user cannot read it.

Diagnostic: run pwd in the same working directory used by the process, then check ls -l config.yml.

Safe fix: place the intended config at ./config.yml, change the working directory, or mount the file at /weatherfeeder/config.yml when using the provided container image.

config load failed: ... parse YAML

Symptom: startup exits with a YAML parse error or an unknown field error.

Likely cause: invalid YAML syntax, multiple YAML documents, or a misspelled config struct field.

Diagnostic: inspect the line and field in the error. Feedkit uses strict YAML field decoding for config struct fields.

Safe fix: correct the YAML and compare the shape with configuration. Driver-specific params keys are validated by their source or sink constructors.

config validation failed

Symptom: startup exits and prints one or more validation messages.

Likely cause: missing sources or sinks, blank names, duplicate source or sink names, invalid mode, missing every for a polling source with mode: poll, or a route that references an unknown sink.

Diagnostic: read every bullet under config validation failed; the loader sorts these messages so multiple issues can be fixed in one edit.

Safe fix: update the top-level config fields as documented in configuration.

unknown source driver

Symptom: startup exits with build source failed.

Likely cause: sources[].driver does not match a registered weatherfeeder source driver.

Diagnostic: compare the configured driver with the source driver table in configuration.

Safe fix: correct the driver name. Current drivers include nws_observation, nws_alerts, nws_forecast_hourly, nws_forecast_narrative, nws_forecast_discussion, nws_weatherstories, openmeteo_observation, openmeteo_forecast, and openweather_observation.

unknown sink driver

Symptom: startup exits with build sink failed.

Likely cause: sinks[].driver is not registered.

Diagnostic: compare the configured driver with the sink driver table in configuration.

Safe fix: use stdout, nats, or postgres.

source expected kinds validation failed

Symptom: startup exits after building a source.

Likely cause: sources[].kinds declares a kind the source does not emit.

Diagnostic: compare the configured kinds list with the source driver kind in configuration.

Safe fix: remove kinds or set it to the kind emitted by that driver.

params.url is required Or params.user_agent is required

Symptom: startup exits with build source failed.

Likely cause: a source is missing required HTTP params, or the values are blank or not strings.

Diagnostic: inspect the named source in the error and check its params.

Safe fix: add non-empty url and user_agent values. See HTTP source params.

url must include units=metric

Symptom: startup exits for an openweather_observation source.

Likely cause: the OpenWeather URL omits units=metric or sets another unit system.

Diagnostic: inspect the query string in params.url.

Safe fix: add units=metric to the OpenWeather current-weather URL. Keep API keys out of committed configs.

source ... sources[].every must be > 0 for polling sources

Symptom: startup exits while building scheduler jobs.

Likely cause: a current weatherfeeder polling source has no usable every interval.

Diagnostic: inspect the named sources[] entry and check every.

Safe fix: set a positive duration such as 1m, 10m, or 1h.

build sink failed ... params.url is required

Symptom: startup exits while building a NATS sink.

Likely cause: the NATS sink is missing params.url, or the value is blank or not a string.

Diagnostic: inspect the named sink in the error and check its params.

Safe fix: set a NATS URL such as nats://localhost:4222.

build sink failed ... params.subject is required

Symptom: startup exits while building a NATS sink.

Likely cause: the NATS sink is missing params.subject, or the value is blank or not a string.

Diagnostic: inspect the named sink in the error and check its params.

Safe fix: set a non-empty subject such as weatherfeeder.

dispatch: sink ... failed consuming event ... NATS sink: connect

Symptom: the daemon starts, but NATS events are not published.

Likely cause: the NATS server URL is unreachable, the server is not accepting connections, or the configured URL is wrong for the runtime network.

Diagnostic: from the same runtime environment, check that the host and port in sinks[].params.url are reachable.

Safe fix: correct the NATS URL or restore broker connectivity. Other configured sinks continue receiving events.

postgres sink ... open db

Symptom: startup exits while building a Postgres sink.

Likely cause: the database URI, username, password, network path, or database availability is wrong.

Diagnostic: inspect sinks[].params.uri, username, and password; verify that the same runtime environment can reach the database.

Safe fix: correct the credentials or URI, restore database connectivity, then restart the daemon.

postgres sink ... ensure table Or ensure index

Symptom: startup exits during Postgres initialization.

Likely cause: the database user cannot create required tables or indexes, an existing object conflicts with weatherfeeder's expected table contract, or the database is unavailable during initialization.

Diagnostic: inspect the named table or index in the error and compare existing database objects with the Postgres table contract.

Safe fix: grant the needed database privileges, create a compatible schema, or perform an operator-managed migration before restarting.

postgres sink: insert into ...

Symptom: the daemon starts, but Postgres writes for some events fail.

Likely cause: a duplicate primary key, incompatible existing table definition, database constraint error, or connection failure during a write transaction.

Diagnostic: inspect the table name and database error in the log. Compare the table with Postgres integration.

Safe fix: repair the database schema or address the duplicate/connection issue. Other configured sinks continue receiving events.

No Events Appear On A Sink

Symptom: the daemon is running but the expected sink receives no events.

Likely cause: the route does not match the event kind, the source has not emitted changed content, or the sink is failing per event.

Diagnostic: check routes, source kinds, and logs for scheduler: poll failed, dispatcher: pipeline error, or dispatch: sink ... failed consuming event.

Safe fix: correct the route or source configuration. If the source uses conditional HTTP and the upstream has not changed, no event is emitted for a 304 Not Modified response; wait for changed upstream content or temporarily set params.conditional: false for diagnosis.

scheduler: poll failed

Symptom: one source logs poll failures while the daemon keeps running.

Likely cause: upstream HTTP error, bad URL, timeout, response body limit, or provider response shape that the source cannot parse.

Diagnostic: inspect the source name in the log and review its HTTP params.

Safe fix: correct the URL, user agent, timeout, or body limit. The next scheduled poll will retry.

dispatcher: pipeline error

Symptom: source polling succeeds, but one event is dropped before sinks.

Likely cause: a normalizer could not decode or map the raw payload, or dedupe received an invalid event ID.

Diagnostic: inspect the error text and the source/schema that produced the event. Review the event wire contract for expected canonical fields.

Safe fix: correct source configuration if it points to the wrong upstream product. If the upstream payload changed shape, update the relevant normalizer and tests.