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.

#"this is not the depot this checkout came from"

Your commands are reaching a different server than the one this working copy was created from. Grixel refuses rather than acting, because submitting here would put your work in the wrong place, and it would look like it succeeded.

Two different things cause it.

Usually: you're pointed at the wrong server. The message names where the setting came from, and that is the thing to fix:

grixel info                # shows both: the server you reached, and the one your checkout came from
echo $GRIXEL_SERVER        # a stale value here beats your saved sign-in

Clear or correct GRIXEL_SERVER, drop a -server flag, or sign in to the right server. Note that grixel login will not help while GRIXEL_SERVER is set, because the environment wins — that's why the message tells you which input to change rather than just saying "log in again".

Occasionally: the server really was replaced. If the address is right and the message says the depot behind it was replaced or rebuilt, your administrator has stood up a new server there. Adopt it explicitly:

grixel info                # run against the NEW server; copy its depot id
grixel rehome <depot-id>   # in your stranded working copy

rehome refuses unless the id you typed is the one that server actually reports, so you can't adopt the wrong server by accident. It also refuses if you have uncommitted changes (submit or copy them out first) or if that server doesn't contain this project's history — in which case take a fresh checkout instead. Your administrator should be telling everyone the depot id when they announce the migration.

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.
connect <server>: handshake failed: <reason> means the server answered but could not complete its version-and-identity handshake. Grixel refuses the connection rather than proceed with its safety checks switched off (a client that cannot learn which depot it is talking to cannot protect you from writing to the wrong one). The reason is the server's own; pass it to your administrator. A server too old to have a handshake at all still connects.

#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"