There is a particular kind of frustration that comes with stale weather data on your website. You check the page, see a temperature from six hours ago, and know — with sinking certainty — that something in the upload pipeline has broken. Again. The station is logging fine. The software is running. But the files are not reaching the server, and the error messages, if they exist at all, are cryptic to the point of uselessness.

I have debugged more FTP upload failures than I care to count, across GraphWeather, WeeWX, CumulusMX, and hand-rolled scripts. The good news: the failure modes are finite and diagnosable. The bad news: they all look the same from the surface — "my website is not updating." This guide gives you a systematic diagnostic process that starts with the most common causes and works toward the obscure. If you are setting up FTP uploads for the first time, the FTP publishing guide is the starting point; this article picks up where that one leaves off, at the moment something goes wrong.

Quick-Answer Summary

Symptom Most Likely Cause First Check
Connection refused Wrong hostname, port, or server down Telnet to port 21 from the station PC
Timeout on connect Firewall blocking outbound FTP Check local firewall, ISP blocks
Login failure Wrong credentials, account locked Test with a standalone FTP client
File listing works but upload fails Permission error on remote directory Check chmod and directory ownership
Upload succeeds but website shows old data Cache, wrong upload path, or encoding issue Clear CDN/browser cache, verify remote path
Intermittent failures Passive mode port conflict, connection limits Enable passive mode, check hosting limits
TLS/SSL handshake error Certificate mismatch or expired cert Verify hostname matches certificate, check date

The Diagnostic Flowchart

Before touching any configuration, answer these three questions in order:

  1. Can you reach the server at all? Open a terminal on the station PC and run:

    telnet yourserver.com 21

    (On Windows, you may need to enable the Telnet client or use Test-NetConnection yourserver.com -Port 21 in PowerShell.)

    If you get a 220 banner, the server is reachable and FTP is running. If the connection hangs or is refused, the problem is network-level — skip ahead to the firewall and ISP section.

  2. Can you authenticate? Use a standalone FTP client (FileZilla, WinSCP, or the command-line ftp tool) with the same credentials your station software uses. If login fails here, the problem is credentials, not your station software.

  3. Can you upload a test file manually? Create a small text file and PUT it to the same directory your station targets. If the manual upload works but the station software fails, the issue is in the software configuration — path, filename, or transfer mode.

This three-step triage eliminates entire categories of problems in under five minutes. Ninety percent of the support requests I have seen could have been resolved at step one or two.

Active vs. Passive FTP

FTP's original design from 1985 assumed direct, unfiltered connectivity between client and server. That assumption died with the first NAT router, and the corpse has been causing problems ever since.

Active Mode

The client connects to the server on port 21 (control channel). When a data transfer starts, the server opens a connection back to the client on a port the client specified. This inbound connection is almost always blocked by the client's NAT router or firewall.

Passive Mode

The client connects to the server on port 21. When a data transfer starts, the server tells the client to connect to a high-numbered port (typically 49152–65535) on the server. The client initiates this second connection outbound, which NAT handles correctly.

Always use passive mode for weather station uploads. Every modern FTP client and station software defaults to passive, but if you are troubleshooting a legacy configuration, this is the first thing to check.

Passive Mode Port Range Issues

Some hosting providers restrict the passive port range but do not advertise it. The server tells the client to connect to port 52437, but the hosting firewall only allows 50000–50100. The result: the control connection works (you can authenticate), but every LIST or PUT command times out.

The fix is server-side — contact your host and ask them to either widen the passive port range or confirm the correct range so you can test against it. On a self-managed server, configure the passive port range in your FTP daemon and open those ports in the firewall:

# vsftpd example
pasv_min_port=50000
pasv_max_port=50100

NAT and Firewall Interference

Local Firewall

Windows Firewall, macOS firewall, and Linux iptables/nftd can all block outbound FTP connections. Weather station software often runs as a background service or a scheduled task — which may have different firewall rules than interactive applications. If FileZilla connects fine but your station software cannot, check whether the software's executable has an outbound rule.

On Windows:

Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*GraphWeather*" }

If nothing comes back, add an outbound allow rule for the executable.

ISP Blocks

Some ISPs block outbound port 21 to combat spam bots that use compromised machines to upload malware to FTP servers. If telnet yourserver.com 21 hangs from your station PC but works from a VPS or your phone on mobile data, the ISP is the culprit.

Workarounds:

  • Switch to SFTP on port 22 — ISPs rarely block SSH. The security guide covers the SFTP migration in detail.
  • Use FTPS on port 990 (implicit TLS) — less commonly blocked than port 21.
  • Use an alternate FTP port if your host supports it — some allow FTP on 2121 or similar.

Double NAT

If your station PC is behind two NAT devices (common when an ISP modem is in routing mode and you have your own router behind it), passive FTP can fail because the server's passive port response references an IP that is unreachable from the client's perspective. The fix: put the ISP modem in bridge mode so you have a single NAT layer.

Hosting Provider Connection Limits

Shared hosting plans typically limit concurrent FTP connections to 3–8 per account. If your station software opens multiple connections in parallel (uploading HTML, images, and data files simultaneously), it can hit this limit. The symptom: most uploads succeed, but one or two files randomly fail on each cycle.

Solutions:

  • Serialise uploads. Configure your station software to upload files sequentially rather than in parallel. GraphWeather's upload scheduler supports this natively.
  • Reduce upload frequency. If you upload every 60 seconds and each cycle takes 20 seconds across multiple files, you may have overlapping cycles. Increase the interval or reduce the file count.
  • Check for zombie connections. If a previous upload timed out without closing cleanly, the server may still count it against your limit. Some hosts expire stale connections after 60–300 seconds; others hold them indefinitely until you contact support.

File Permission Errors

A successful FTP login does not guarantee write access. The remote directory must be writable by the FTP user. Common symptoms:

  • 550 Permission denied on PUT.
  • 553 Could not create file on upload.
  • Upload appears to succeed (no error), but the file is zero bytes on the server.

Checking Permissions

Connect via SSH (if available) and run:

ls -la /var/www/html/weather/

The FTP user (or the group it belongs to) needs write permission on the target directory. If the directory is owned by www-data and your FTP user is weatherftp, either add weatherftp to the www-data group or change the directory permissions:

chmod 775 /var/www/html/weather/
chown www-data:weatherftp /var/www/html/weather/

On shared hosting, use the hosting control panel's file manager to check and adjust permissions. The target directory should be 755 at minimum, and the files within it 644.

Overwrite vs. Create

Some FTP servers disallow overwriting existing files while permitting creation of new files (or vice versa). Weather station uploads typically overwrite the same files on every cycle (current.html, realtime.txt). If your server requires the old file to be deleted before a new one can be written, configure your station software to delete-then-upload rather than direct overwrite. This is an uncommon but documented issue with certain ProFTPD configurations.

Disk Space Issues

A full disk on the server silently kills uploads. The FTP server accepts the connection, authenticates successfully, and may even begin the transfer — but the file ends up truncated or missing. Error messages vary: some servers return 452 Insufficient storage, others simply disconnect mid-transfer.

Check available space:

df -h /var/www/html/

If you have been uploading images alongside HTML (webcam snapshots, chart images), they accumulate. A 5 MB webcam image uploaded every 5 minutes is 1.4 GB per day. Set up a cron job or server-side script to prune old images, or configure your station software to overwrite a single file rather than creating timestamped versions. The image refresh and caching guide covers strategies for managing image uploads efficiently.

Encoding Problems in Filenames

Weather station software is often developed in a specific locale. Filenames containing accented characters, spaces, or special characters can cause upload failures when the server expects a different encoding. The safest approach: use only ASCII alphanumeric characters, hyphens, and underscores in filenames. No spaces. No accents. No parentheses.

If your station software generates filenames automatically (e.g., données_météo_2026-04-06.html), check whether you can override the naming template. GraphWeather and WeeWX both allow custom filename patterns in their template configuration.

TLS/SSL Certificate Errors

If you use FTPS (FTP over TLS), certificate issues are a common failure point:

  • Hostname mismatch: The certificate is issued for www.example.com but your FTP configuration points to example.com or an IP address. Use the hostname that matches the certificate's Common Name or Subject Alternative Name.
  • Expired certificate: Let's Encrypt certificates expire every 90 days. If auto-renewal fails, FTPS connections break. Check the certificate expiry with openssl s_client -connect yourserver.com:21 -starttls ftp.
  • Self-signed certificate: The station software rejects the certificate because it is not signed by a trusted CA. Either install the CA certificate on the station PC or configure the software to accept self-signed certificates (less secure but sometimes necessary on internal servers).

As a general rule, if TLS is causing you grief, the simplest upgrade path is switching to SFTP entirely — it sidesteps certificate management because SSH uses key-based authentication. The security guide walks through the migration.

Stale Data vs. Failed Upload

This is the distinction that costs the most debugging time. Your website shows old data — but is it because the upload failed, or because the upload succeeded but the browser (or CDN) is serving a cached version?

How to Tell

  1. Check the file modification time on the server. SSH in and run ls -la /var/www/html/weather/current.html. If the timestamp is current, the upload is working — the problem is caching.
  2. Check the station software's upload log. GraphWeather, WeeWX, and CumulusMX all log upload successes and failures. If the log shows success but the server file is stale, look at whether you are uploading to the correct path.
  3. Bypass the cache. Load your page with ?v=12345 appended to the URL, or open it in an incognito window. If the data is current, the problem is purely browser or CDN caching.

Cache-Related Staleness

If uploads are succeeding but the website shows old data:

  • Browser cache: Add cache-control headers to your weather pages. Cache-Control: no-cache, must-revalidate forces the browser to check for fresh content on every load.
  • CDN cache: If your site is behind Cloudflare, Fastly, or another CDN, purge the cache for the affected URLs. Better yet, configure a page rule that sets a low TTL (30–60 seconds) for your weather data pages.
  • Intermediate proxies: Corporate networks and ISPs occasionally cache content. The Cache-Control header handles most cases; adding Pragma: no-cache covers legacy proxies.

The image refresh and caching guide goes deep on this topic, including techniques for cache-busting webcam images and chart graphics that update on a schedule.

Atomic Upload Patterns

A subtle but important issue: if your station software uploads a file while the web server is simultaneously serving it, the visitor may receive a partially written file — a truncated HTML page, a half-updated data table, or a corrupted image.

The fix is atomic upload: write the file to a temporary name (e.g., current.html.tmp), then rename it to the final name (current.html). The rename operation is atomic on most filesystems — the web server either sees the old file or the new file, never a partial one.

Most station software supports this pattern:

  • GraphWeather: Enable "upload with temporary name" in the FTP settings.
  • WeeWX: Uses atomic uploads by default in recent versions.
  • CumulusMX: Supports temporary file upload in its FTP configuration.

If your software does not support atomic uploads, a server-side script that moves the file after upload achieves the same result.

Testing with Command-Line FTP Clients

When all else fails, drop to the command line. GUI FTP clients sometimes hide errors or apply their own connection logic that obscures the real problem.

Windows PowerShell

# Basic connectivity test
Test-NetConnection yourserver.com -Port 21

# SFTP test with OpenSSH
sftp [email protected]

Linux / macOS

# Verbose FTP session
ftp -v yourserver.com

# Curl-based upload test
curl -v -T testfile.txt ftp://user:[email protected]/weather/

# SFTP test
sftp -v [email protected]

The -v flag is your best friend during troubleshooting. It shows every protocol exchange — the PASV response, the port negotiation, the exact error code on failure.

Common Mistakes

  1. Blaming the software when it is a network issue. If FileZilla cannot connect, your station software cannot either. Always test with an independent client first.

  2. Not checking server-side logs. Your hosting provider logs every FTP connection. If you can access /var/log/vsftpd.log or equivalent, the server's perspective often reveals what the client-side error message does not.

  3. Uploading to the wrong directory. A trailing slash, a missing subdirectory, or a case-sensitive path on a Linux server can all cause silent failures. Always verify the exact remote path by listing the directory contents from an FTP client.

  4. Ignoring upload frequency vs. transfer time. If uploading 15 files takes 45 seconds and your interval is 60 seconds, you have a 15-second margin. Add a slow connection day, and cycles overlap. Either reduce the file count, increase the interval, or compress files before upload.

  5. Not testing after making changes. Every configuration change — new password, new server, new path — deserves an immediate manual upload test. Do not wait for the next scheduled cycle and hope for the best.

  6. Forgetting about file size limits. Some shared hosting plans limit individual file sizes (often 10 MB or 50 MB). Large chart images or data archives can be silently rejected. Check your host's limits.

Related Reading

FAQ

My station software says "upload successful" but the file on the server has not changed. What is happening? The software is likely uploading to the wrong directory. FTP servers often drop you into a home directory that is not the web root. Check the full remote path — it might need to be /public_html/weather/ rather than /weather/. List the remote directory contents from a manual FTP session to confirm.

How do I debug intermittent upload failures that happen once or twice a day? Enable verbose logging in your station software and check the timestamps of failures. If they cluster around the same time daily, look for scheduled server maintenance, backup jobs that spike server load, or ISP DHCP lease renewals that briefly drop connectivity. If they are random, suspect connection limits or network instability — a persistent SFTP connection (rather than reconnecting each cycle) can help.

Should I use active or passive FTP? Passive. Always passive. Active FTP requires the server to connect back to your station PC, which is blocked by virtually every NAT router and firewall in existence. The only scenario for active FTP is a direct LAN connection with no NAT — essentially never in a home station setup.

Can I use SCP instead of SFTP? SCP works for one-off file transfers but lacks SFTP's directory listing and resume capabilities. For automated station uploads that need to verify the remote path and overwrite specific files, SFTP is the better choice. Both use SSH for transport, so the security is identical.

My host limits FTP connections to 3. How can I upload 20 files per cycle? Queue them sequentially on a single connection rather than opening parallel connections. Most station software has a "single connection" or "sequential upload" mode. Alternatively, bundle files into a compressed archive, upload the archive, and use a server-side cron job to extract it — though this adds complexity.