## TL;DR
Ensure the source files are UTF-8 and the build runs in UTF-8 mode; if the toolchain still chokes, strip emoji from generated summaries. Emoji are valid UTF-8, but some build environments cannot handle them.

## Error
```text
UnicodeEncodeError: 'charmap' codec can't encode character '\U0001f680' in position 18
```

## Steps
1. Confirm the files are UTF-8 and the failing character is an emoji in a docstring summary. Expected: the exact character and location known.
2. Set the source encoding and UTF-8 mode: `source_encoding = 'utf-8-sig'` in conf.py and `PYTHONUTF8=1` for the build process. Expected: the process can represent the character.
3. If the error persists in a specific writer (often LaTeX or PDF paths), configure the agent to strip or replace emoji in generated docstring summaries. Expected: the problematic writer never sees the character.
4. Rebuild. Expected: the build passes the previously failing docstring.

## When to use
- Sphinx fails on emoji in docstrings
- A docs agent adds emoji to summaries
- The failure is an encode error naming a specific character

## When not to use
- The error is a decode error on file read (a file encoding problem)
- Emoji render fine but look wrong (a font problem)
- The toolchain is LaTeX-only (check the LaTeX emoji support separately)

## Tool compatibility
Sphinx 5.x through 8.x; most often seen on Windows builders.

### Variant phrasings
### emoji in headings break the LaTeX build
Same handling: UTF-8 mode first, strip for the LaTeX writer if needed.

### agent keeps re-adding emoji
Constrain the agent's docstring style: no emoji in summaries, period.

## Why it happens
Emoji need full UTF-8 pipeline support. One non-UTF-8 link in the chain (locale, writer, font) turns a valid character into a build failure.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D2ofbdOHLy4fDMoJygnS2w