In the event the local copy of the repository catalogue get corrupted the command "pkg update -f" must be run. I propose a change to both the error message and the PKG-UPDATE man page to suggest this. User's having been googling for this answer since 2014. I started using FreeBSD with version 4.5 and never hit this error until updating from 10.3 --> 11.3. I also had to google for the answer.
Better yet, pkg should be able to detect this condition and perform the equivalent `pkg update -f` itself (unless `--no-repo-update` was specified).
pkg now recommends to run pkg update -f, the bug is on the cluster side not on pkg side.
It's a design problem. We know package syncs are never going to be instantaneous, but the design of the pkg server infrastructure and client does not allow the client to install from a consistent snapshot (or even recognize the condition of an inconsistent sync status). A better design would be to use content-addressed names on the server (i.e., some hash). If the client gets a 404 error, it knows it has a stale index and must re-fetch metadata (automatically). If the client does not get a 404, it will get exactly the file it asked for (modulo HTTP layer corruption) and the size check will not fail anyway. Debian talks about something like this: http://www.chiark.greenend.org.uk/~cjwatson/blog/no-more-hash-sum-mismatch-errors.html