Troubleshooting
Not logged in, the approval page refusing, the local network permission, exit codes, Liquid parse skipped, Windows file names, logs.
"not logged in" / the server does not accept the key
not logged in to store 42 on https://webmati.com/graphql — run `webmati login --key <key>` (or `webmati login --web`), or set WEBMATI_TOKEN
This machine has no key for that website, or the key expired (30 days) or was revoked. Sign in again; inside a project no flags are needed:
webmati login --web
When the environment variable WEBMATI_TOKEN is set, it is always used instead
of the saved key — a stale token there causes this error too: unset WEBMATI_TOKEN.
The approval page in the browser refuses
The page speaks Vietnamese; its messages are below with a translation.
| The page says | Why | Do |
|---|---|---|
| Liên kết đăng nhập không hợp lệ (invalid sign-in link) | the link is old or was changed | run webmati login --web again |
| Không mở được website này (cannot open this website) | the website is not in the workspace you have open, or you have no rights on it | switch workspace in the top bar, or open that website in the admin once and try again |
| Workspace này chưa có website nào (no website in this workspace) | the open workspace is empty | pick another workspace, or create a website first |
| Không gửi được key tới CLI trên máy này (could not hand the key to the CLI) | the CLI already exited (after 5 minutes), or the browser blocked 127.0.0.1 | run webmati login --web again; the key it just made was revoked |
| Đã huỷ (cancelled) | you pressed Cancel | no key was created |
The local network permission (Chrome)
When the page hands the key to the CLI, Chrome may ask for permission to reach
devices on your local network. Choose Allow: the destination is the CLI on
your own machine (127.0.0.1). If you blocked it: click the icon at the start of
the address bar ▸ Site settings ▸ allow Local network, then run
webmati login --web again. Without a usable browser, sign in with a key:
login --key -.
Exit codes
| Code | Meaning | Usually when |
|---|---|---|
1 | error | network, permissions, a file that cannot be read |
2 | bad usage | a missing argument, an unknown flag (webmati <command> --help) |
3 | needs your attention | conflicts, validation errors, refused changes, a data-losing change without --allow-destructive |
4 | the CLI is too old | run webmati update |
"Liquid parse skipped"
Liquid parse skipped (install Node ≥18 or use --remote)
The offline Liquid syntax check needs Node.js 18 or newer
(nodejs.org). The step was skipped, not passed: install
Node, or run webmati validate --remote to let the server check it.
Odd file names on Windows (~3A…)
Names that are not valid on Windows are encoded on the way down and decoded on the way up:
| On the server | In the project |
|---|---|
stripe:pay (an app's workflow) | stripe~3Apay |
con, nul, aux… | con~, nul~, aux~ |
| a name ending in a dot or a space | its last character becomes ~2E / ~20 |
Do not rename them yourself. Two paths that differ only in upper/lower case are refused when you clone, since macOS and Windows treat them as one file.
"not inside a webmati project"
The command needs the project folder (the folder with webmati.toml, or one
below it). cd there, or put --dir in front of the command:
webmati --dir ~/sites/my-shop status
The platform refuses something it should not
A refusal that looks wrong, a command that fails the same way every time, a limit that blocks the job: do not work around it, report it. Right after the command that failed:
webmati issue new --attach-last
It asks for a title and a description (both public: no keys, no customer data),
looks for the same report and offers to +1 it instead, and sends as private
context only you and the platform team see: this CLI's version, the OS, the website,
and the command that failed with its error and output and the end of
.webmati/logs, tool arguments left out and secrets redacted. An agent passes it all
on the command line:
webmati issue new --json --kind bug --title "push refuses a 300 KB section" --body-file report.md --attach-last
Under --json a report that looks like an existing one exits 3 with the matches:
+1 one (webmati issue vote 12 --note "also on Windows") or file it anyway with
--yes. webmati issue list --mine follows yours, and webmati issue show 12 reads
the answers. A key from before the issues hub is refused with missing scope: issues:…: run webmati login --web once.
Where the logs are
| File | What |
|---|---|
.webmati/logs/tools.jsonl | every webmati tool call |
.webmati/logs/exec-<time>.jsonl | every tool call a webmati exec script made |
.webmati/logs/last-failure.json | the last command that failed, for webmati issue new --attach-last (outside a project: ~/.config/webmati/last-failure.json) |
.webmati/conflicts/ | the server's side of items in conflict |
~/.config/webmati/update.json | the latest update check |
--verbose prints every HTTP request (operation, status, duration), never a key
or a body:
webmati --verbose push --dry-run