Summary
On Windows, keyring_backend: file is unusable because the backend writes files whose names contain colons (e.g. token:default:user@gmail.com). NTFS treats : as the Alternate Data Stream separator, so os.OpenFile fails with ERROR_INVALID_NAME before any token can be stored.
Any command that needs to read/write the keyring produces:
store token: open C:\Users\<user>\AppData\Roaming\gogcli\keyring\token:default:<email>: The filename, directory name, or volume label syntax is incorrect.
Reproduction
- Fresh Windows 11 install (happens on 10 as well).
gog config set keyring_backend filegog auth add --account you@gmail.com
Result: OAuth flow completes, token is fetched from Google, then gog errors while storing it. AppData\Roaming\gogcli\keyring\ remains empty.
Same error appears on any subsequent gog auth list, gog auth tokens export, etc.
Environment
- OS: Windows 11 Home 26200 (also reproducible on Win 10)
- Shell: Git Bash (MSYS2) — also reproduces from
cmd.exe and PowerShell 7
- gog: v0.12.0 (c18c58c)
- Filesystem: NTFS (default)
Root cause
gog uses github.com/99designs/keyring. The file backend builds its on-disk path by concatenating the item's Key into the filename without sanitizing characters illegal on NTFS. gog stores refresh tokens under keys shaped like token:<client>:<account-email>, which contains two colons — both invalid in NTFS filenames. The backend has the same issue on macOS/Linux only if the key contains /, which it doesn't, so this is Windows-specific.
This is distinct from #395 (CI test skips) — this is a runtime crash on real user machines. It's the most likely reason a Windows user hits auto backend's fallback; except auto isn't the default everywhere, so anyone who ran gog config set keyring_backend file (including anyone who followed docs written with Linux/macOS in mind) is stuck with no tokens.
Suggested fix
In the keying code that derives the on-disk filename, sanitize characters illegal on Windows before passing to the file backend. Minimal patch: replace :, <, >, ", |, ?, * with _ (or URL-encode them). Colon is the one that actually bites; the others are covered here for completeness.
Alternatively, hash the key (e.g. SHA-256 hex) for the filename and keep the original key inside the file body — this is what most keyring implementations do. 99designs/keyring may need patching upstream, or gog can wrap the backend with a key-sanitizing shim.
Workaround
gog config set keyring_backend auto — this picks wincred (Windows Credential Manager / DPAPI) on Windows and works correctly. Only viable as a workaround because wincred is accepted as valid by auto resolution but rejected as a literal value in keyring_backend (the error message says "expected auto, keychain, or file" — wincred is not listed). So auto is the only path.
Related
Summary
On Windows,
keyring_backend: fileis unusable because the backend writes files whose names contain colons (e.g.token:default:user@gmail.com). NTFS treats:as the Alternate Data Stream separator, soos.OpenFilefails withERROR_INVALID_NAMEbefore any token can be stored.Any command that needs to read/write the keyring produces:
Reproduction
gog config set keyring_backend filegog auth add --account you@gmail.comResult: OAuth flow completes, token is fetched from Google, then
gogerrors while storing it.AppData\Roaming\gogcli\keyring\remains empty.Same error appears on any subsequent
gog auth list,gog auth tokens export, etc.Environment
cmd.exeand PowerShell 7Root cause
gog uses
github.com/99designs/keyring. Thefilebackend builds its on-disk path by concatenating the item'sKeyinto the filename without sanitizing characters illegal on NTFS. gog stores refresh tokens under keys shaped liketoken:<client>:<account-email>, which contains two colons — both invalid in NTFS filenames. The backend has the same issue on macOS/Linux only if the key contains/, which it doesn't, so this is Windows-specific.This is distinct from #395 (CI test skips) — this is a runtime crash on real user machines. It's the most likely reason a Windows user hits
autobackend's fallback; exceptautoisn't the default everywhere, so anyone who rangog config set keyring_backend file(including anyone who followed docs written with Linux/macOS in mind) is stuck with no tokens.Suggested fix
In the keying code that derives the on-disk filename, sanitize characters illegal on Windows before passing to the file backend. Minimal patch: replace
:,<,>,",|,?,*with_(or URL-encode them). Colon is the one that actually bites; the others are covered here for completeness.Alternatively, hash the key (e.g. SHA-256 hex) for the filename and keep the original key inside the file body — this is what most keyring implementations do. 99designs/keyring may need patching upstream, or gog can wrap the backend with a key-sanitizing shim.
Workaround
gog config set keyring_backend auto— this pickswincred(Windows Credential Manager / DPAPI) on Windows and works correctly. Only viable as a workaround becausewincredis accepted as valid byautoresolution but rejected as a literal value inkeyring_backend(the error message says "expected auto, keychain, or file" —wincredis not listed). Soautois the only path.Related