Fix urlwatch Errors Caused by a Changed Website URL
Update a urlwatch job after a page moves, preserve its history with --change-location, and tell URL changes apart from connection or HTTP errors.
When a monitored page moves, update its urlwatch job with urlwatch --change-location OLD_URL NEW_URL. This documented command changes the job location while retaining its history. Editing the URL directly in urls.yaml creates a new job with no history. First verify that the destination really changed; a temporary connection error or an HTTP error is not proof of a move.
1. Find the affected job and verify the destination
- Inspect your job list in
urls.yaml, or open it withurlwatch --edit. - For a URL job, identify the job’s
urlfield. URL jobs require this field. - Check the intended new address and confirm it returns the content you want to monitor. urlwatch watches pages and reports changes as a unified diff, so make sure the destination still represents the same thing for your monitoring purpose.
- Distinguish a genuine move from a temporary connection problem or an HTTP error. urlwatch reports errors by default; changing the job location is appropriate only when the location itself has changed.
2. Change the location and keep the job history
Run the command with the exact old and new locations:
urlwatch --change-location https://example.org/old https://example.org/newReplace both example addresses with the locations in your affected job. Do not infer a new path from an error message: confirm it from the site’s own links, documentation, or another reliable source. The command also applies to Browser and Shell jobs: it changes navigate and command, respectively.
Why not edit urls.yaml directly?
urlwatch stores job history based on the value of the url parameter. Replacing that value directly in urls.yaml creates a new job with no history. Use --change-location when the old and new locations are the same monitored job and you want its past results to remain associated with it.
3. Check that monitoring works at the new address
After changing the location, run urlwatch as you normally do and inspect the result. Confirm that the job reaches the new page and that the retrieved content is the content you intended to watch. If the URL still produces an error, diagnose that error before changing configuration to suppress it.
Diagnose errors that look like URL changes
| What you observe | What to check | Next step |
|---|---|---|
| The page has moved to a confirmed new address | Verify the new page is the intended monitored content | Use urlwatch --change-location OLD_URL NEW_URL to keep history |
| A connection error | Check whether the failure is temporary and whether the destination is reachable | Retry or investigate the connection; do not treat the error alone as evidence of a move |
| An HTTP error | Check the status and whether the site is temporarily returning an error or the path is no longer valid | Confirm the correct destination before updating the location |
| The URL job returns incomplete or unsuitable content | Determine whether the page relies on JavaScript to render the content being monitored | Consider a Browser job if a URL job does not return the right results |
Configuration choices and edge cases
Ignoring errors is not the same as fixing a moved URL
urlwatch documents per-job options for ignoring connection errors and selected HTTP error codes. These options suppress error reporting; they do not establish that a page moved or fix an incorrect destination. Use them only when suppressing those reports is actually the desired behavior, not as a substitute for confirming and updating a moved location.
When a Browser job may help
If the destination depends on JavaScript and a URL job does not retrieve the content you need, a Browser job is a possible fallback. Browser jobs require Playwright and are resource-intensive. The urlwatch handbook recommends them only when a URL job does not return the right results.
History and identity
The important decision is whether the new location represents the same monitoring job. If it does and history matters, use the documented location-change command. If you deliberately want a separate job with a fresh history, editing or creating a job may be appropriate. Be precise with the old location so you update the intended job.
Troubleshooting
- The command does not appear to change the job: Check that the old location exactly matches the job location and that the new location is the confirmed destination. For Browser and Shell jobs, the location fields are
navigateandcommand. - The job has no past history after the change: A direct URL edit creates a new job without history. The handbook’s documented method for retaining history is
--change-location; check whether the URL was edited directly or whether the old location matched the intended job. - The error remains after changing the URL: The failure may be a connection problem or an HTTP error rather than a location change. Verify the destination and diagnose the reported error before configuring any ignore options.
- The new page loads but the monitored content is missing: If the page renders the content with JavaScript, assess whether a Browser job is needed. Account for its Playwright dependency and higher resource use.
- The diff is unexpectedly large after the move: Confirm that the new address serves the intended page and comparable content. urlwatch reports content changes as unified diffs; a different destination or page structure can change the result substantially.
Performance, reliability, and cost
The core fix is a command-line job-location change; no physical product is needed. A URL job is the simpler choice when it returns the desired content. Browser jobs consume more resources and require Playwright, so use one only when JavaScript rendering is necessary for the monitored result. For reliability, verify the destination and separate connection and HTTP failures from an actual move. The supplied urlwatch documentation does not establish a cost or success-rate figure for this fix.
Or skip the browser setup
If your goal is to capture a page as an image or PDF rather than maintain a urlwatch change-monitoring job, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. The DIY urlwatch location change above remains the right remedy for a moved monitoring job.
ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
For options and API details, see the ScreenshotNeo documentation. Example cURL request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.org/new -o shot.webpSign up for 1,000 free screenshots a month, with no card required.
FAQ
Does –change-location work for Browser and Shell jobs?
Yes. It changes the navigate value for Browser jobs and the command value for Shell jobs.
Should I ignore an HTTP error after a page move?
Not as a way to fix the move. First confirm the intended address. Ignore options suppress selected errors; they do not update the job location.
Which urlwatch version introduced this command?
The project changelog lists --change-location among additions in version 2.26, dated 2023-04-11. The reviewed handbook identifies itself as version 2.29; these materials do not establish which version is latest.
Sources
- urlwatch handbook: updating a URL while keeping past history, URL job configuration, error handling, and Browser jobs.
- urlwatch project changelog: version 2.26 entry for
--change-location.
