Skip to content

Windows: raea writes a \\?\ verbatim path into .git/config, breaking every git command — workspaces unusable and the app cannot finish first run #169

Open

Description

@jonathanbokvad

Environment

  • Windows 11 Home 10.0.26200
  • raea CLI 0.1.6 (irm https://raea.io/install.ps1 | iex)
  • raea desktop app 0.1.6 (raea-0.1.6-windows-x86_64.app.exe)
  • git version 2.50.1.windows.1

The renderer is fine — raea render, raea check, raea guide and the whole
compositions workflow all work well. What follows is confined to workspaces.


Bug 1 (blocking): raea writes a Windows verbatim path into .git/config

When raea creates or initialises a workspace it wires .raea/workspace into the repo
with an [include] in .git/config. On Windows it writes it like this:

[include]
	path = ../../../../../../../../\\\\?\\C:/\\/Users/USER/Documents/raea/my-studio/.raea/workspace

Git for Windows cannot open a \\?\ verbatim path, so from that moment every git
command in the repository fails:

$ git -C C:\Users\USER\Documents\raea\my-studio status
fatal: unable to access '.git/../../../../../../../../\\?\C:/\/Users/USER/
Documents/raea/my-studio/.raea/workspace': Invalid argument

This one fault is the root cause of all of the following:

Command Result
raea workspace adopt . REFUSED git config workspace.id ws_…: could not lock config file …: Invalid argument
raea project new NAME same refusal on projects/NAME/.raea/project
raea doctor --fix 3 of 4 fixes fail with the same error
raea workspace --json returns "id":null,"name":null,"layout":null for a real workspace
app → Make workspace fatal: unable to access … Invalid argument, workspace never registers

raea workspace init — which the app itself recommends in its error text ("cd there
and raea workspace init re-adds its includes") — re-writes the broken line every
time
, so the suggested remedy reintroduces the bug.

Fix

The include should be the plain relative path, which works:

[include]
	path = ../.raea/workspace

With that substituted by hand, git runs normally and the fields resolve:

$ git -C <ws> config workspace.id      # ws_094174b4
$ git -C <ws> config workspace.name    # My studio
$ git -C <ws> config workspace.layout  # monorepo

Note that raea's own reads appear to use the verbatim path too: even after the repair,
raea workspace --json still reports id/name/layout as null while printing
"path":"\\\\?\\C:\\Users\\...". So stripping the \\?\ prefix is likely needed on both
the read and write sides (e.g. a dunce-style simplification after canonicalize).

Bug 2: the workspace root is doubled when raea.root is unset

With git config --global raea.root unset, the app created:

C:\Users\USER\Documents\raea\Documents\raea\test-raea

while its own UI displayed the intended C:\Users\USER\Documents\raea › test-raea.
The default root is joined twice. Setting raea.root explicitly
(git config --global raea.root "C:/Users/USER/Documents/raea") fixes the doubling —
but not Bug 1.

Bug 3: first run cannot be completed on Windows

Both branches of the app's Make workspace step dead-end:

  • Folder does not exist → the app scaffolds it (.git, .raea/workspace,
    projects/, shared/*, .gitattributes, taste.ts), then its final git add fails
    because of Bug 1. The workspace is never registered: ~/.raea/feed/storage/local.json
    still has "workspaces":[] and the sidebar still reads "No workspace yet".
  • Folder already exists (including one the app itself half-created) → it refuses with
    "… is a workspace already: cd there and raea workspace init re-adds its includes",
    and again never registers it. Repairing the include and committing the repo first does
    not change this.

Net effect: on Windows the app cannot get past "Set up your workspace", so the feed,
raea show, notes and the review loop are all unreachable.

A stale .git/index.lock is also left behind by the failed git add, which blocks the
next git write until removed.

Bug 4 (cosmetic, but misleading): macOS wording on Windows

raea show on Windows reports:

The raea app isn't on this Mac, so it opened in the Mac's own viewer: nothing was
posted and nothing comes back. Install raea (raea.io) to show work as items the
person can answer.

This is printed on Windows, with the app installed and running. The install state it
reports is also wrong, though that may just be Bug 1 in another guise.

Bug 5 (minor): raea.io/download/windows 404s on HEAD

curl -I https://raea.io/download/windows → 404 Not Found. A GET works and redirects
to the GitHub release asset. Anything probing with HEAD concludes there is no Windows
build.

Bug 6 (minor): no Intl in the composition runtime

Number.prototype.toLocaleString throws ReferenceError: Intl is not defined at render
time. Easy to work around, but worth either polyfilling or documenting.

Bug 7 (minor): --quality master cannot save the darks on Windows

On a very dark picture, raea check reports blotching … the encoder starved the near-blacks, and --quality master does not help, because Windows falls back to
openh264 / H.264 Constrained Baseline. Rendering PNG frames and encoding with x264 at
crf 15 clears the check. Worth either documenting or letting --quality pick a better
encoder when one is present.


Workaround in use

tools/fix-raea-git-include.ps1 strips any \\?\ include from a workspace's
.git/config, restores path = ../.raea/workspace, and verifies that git runs and the
workspace fields resolve. It must be re-run after any raea command that touches a
workspace or project.


Related

shinyobjectz/raea#78 (closed) was the same class of fault on the bundler side — a
\\?\ verbatim path leaking into a consumer that cannot read one. This one is in the
git integration, so a shared "simplify the path before handing it to anything external"
helper would likely cover both.

Activity

  1. changed the title [-]Windows: raea writes a \\\\\?\\\ verbatim path into .git/config, breaking every git command - workspaces unusable and the app cannot finish first run[/-] [+]Windows: raea writes a \\?\ verbatim path into .git/config, breaking every git command — workspaces unusable and the app cannot finish first run[/+] on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions