Syntax errors in production only: should SWI-Prolog encoding be pinned in source or in deployment config?

Answer the core question first

Adding :- encoding(utf8). as the very first term in every source file is sufficient to make the file load correctly in all three common run modes (CLI, REPL and when the file is part of a saved state built with qsave_program/2). The directive forces the parser to interpret the file’s byte stream as UTF‑8, overriding the LANG/LC_ALL settings of the host environment.

Why it works

• The directive is processed before any other term; if it appears after code, SWI‑Prolog will have already read the file using the default locale and the directive will be ignored.
• When a saved state is created, the directive is applied at load time for each file that is parsed. The resulting predicates are stored in the state with the correct atom values.
• There are no documented cases in SWI‑Prolog 9.x where a deployment‑level locale overrides an in‑file encoding/1 directive. The directive takes precedence.

Potential pitfalls

• BOMs: UTF‑8 files that start with a Byte‑Order Mark are not recognised by SWI‑Prolog, causing the directive to be mis‑parsed. Strip any BOM before adding the directive.
• Saved‑state consistency: If a saved state is built on a host with a different locale than the target host, the directive may be ignored for files that were already parsed before the directive was seen. Rebuild the state on a machine that matches the target locale (or build it on a locale‑neutral machine and keep the directive in all source files).
• Other locale‑dependent behaviour: The locale still influences things like error message language and the format of write/1 output. If those aspects matter for your production logs, keep LANG consistent as well.

Recommended practice for teams without full control of the production host

1. Pin the encoding in source – place :- encoding(utf8). as the first term in every file that contains non‑ASCII characters. Verify the file has no BOM.
2. Build saved states on a consistent environment – use a build machine with the same locale (e.g. LANG=en_US.UTF-8) or a neutral locale (e.g. LANG=C) and rebuild the state whenever the source changes.
3. Document the convention – add a note to the repository’s README or a dedicated ENCODING.md explaining that the directive is required and why.
4. Test on a “production‑like” host – before deployment, load the code (or the saved state) on a machine that mimics the target locale and verify that no syntax errors appear and atoms are correct.

Follow‑up diagnostic detail

To fine‑tune the recommendation, could you confirm whether the production server’s LANG environment variable is set to en_US.UTF-8 or something else? Knowing the exact locale helps ensure the build environment matches the target and that no hidden locale differences remain.