Troubleshooting

Common messages and what to do about them.

If grixel login fails with something like error reading server preface … frame too large … looked like an HTTP/1.1 header, you're pointing the client at a port that answered plain HTTP, not Grixel's gRPC. Grixel connects over gRPC by default, so the server URL must point at the gRPC port.

Look at the server's startup banner — it prints the exact URL to use, e.g. connect a client: grixel login -server grpc://HOST:8090 .... Use that.
Make sure the port isn't taken by another program (lsof -nP -iTCP:8090 -sTCP:LISTEN).
If you specifically want the HTTP fallback transport, use an http:// URL against the HTTP port instead: grixel login -server http://HOST:8080 -token <token>.

#"behind head" when you submit

Someone else submitted to the project since you last synced. Pull their changes, settle any conflict, then submit again:

grixel sync
grixel submit -m "..."

#"not found" for something you expected to see

You may not have access to that path — Grixel says "not found" rather than "access denied" for anything you're not allowed to see. Confirm your account, and if it still isn't there, ask your administrator for access:

grixel whoami

See Sharing and visibility for why it works this way.

#A file is locked by someone else

A binary file you want to edit is claimed by a teammate. Check who holds it and coordinate with them:

grixel locks

You won't be able to submit changes to it until they release the lock (which happens automatically when they submit).

#A conflict after sync

You and someone else changed the same text file. Settle it:

grixel resolve --mine <path>      # keep yours
grixel resolve --theirs <path>    # take theirs
grixel mergetool                  # combine by hand

Then submit.

#I committed a secret (or a huge file) by mistake

First, if it's a secret: rotate it — revoke the exposed keys/passwords and issue new ones. Deleting the file afterwards is not enough on its own. Then see Removing files for removing it going forward and what purging from history involves (an admin operation).

#`status` says it skipped some symlinks

Grixel doesn't version symlinks, so any symlink in your working tree is skipped — status lists them under a skipped : line so you know:

skipped  : 2 symlink(s) — not versioned (Grixel doesn't track symlinks)
             Sounds
             Layouts
           → if any hold content you want in the depot, replace the link with the real files

If the link points at build output or a shared cache, that's fine — leave it. If it points at real content you want in the depot, replace the symlink with the actual files (for example cp -RL <target> <name>) before you submit, or it won't go up.

#A promotion is blocked

The protected area still needs sign-offs. See what's missing:

grixel review outstanding

Get the required approvals in, then promote again. See Review and sign-off.

grixel whoami shows whether you're signed in and to which server.
If a command can't reach the server, check the server address and that your token is still valid; your administrator can issue a new one.
grixel version confirms which version you're running; re-run the installer to update.

#The `grixel` command isn't found

The install location isn't on your PATH. Re-run the installer and follow the printed PATH hint, then open a new terminal. See Install.

#Still stuck?

Every command explains itself with -h, for example grixel submit -h.

#Login fails with "frame too large" / "HTTP/1.1 header"