Web API errors
The workflow --web API answers a failed request with an
RFC 9457 problem details object, sent
as application/problem+json. (The loopback, same-origin and dry-run guards
refuse a request as plain text before it reaches the API, so those few
responses are not problem details.)
{
"type": "https://jacob-delgado.github.io/workflow/docs/errors/#not-found",
"title": "Not found",
"status": 404,
"detail": "issue PROJ-412 was not found",
"code": "not_found"
}type— a stable URI naming the problem; it points at the matching section below.title— a short, fixed summary of the problem type.status— the HTTP status code.detail— what went wrong this time, safe to show. It is curated: it never carries a secret (tokens are redacted before an error is formed) or an internal host. A write that is refused may include the git or forge’s own reason so you can act on it; a read failure and an unreachable upstream stay generic.code— a stable, machine-readable reason, for a client to switch on rather than parsing prose.retry_after— only on a Rate limited problem, and only when the upstream said: how many seconds it asked to wait. The answer’sRetry-Afterheader says the same.fields— only on an Unprocessable configuration save refused as not valid: each setting the validation refused, as akey(its dotted name in the file, such asbranch.slug_limit) and adetail(why), so a form can mark the setting itself. Thedetailbeside them joins the same reasons on one line.
The codes below are the whole set.
Bad request
Status 400. The request could not be understood — a malformed body, or one
with an object that names the same key twice; a query or path parameter that
did not fit the contract (a task write whose uuid is not one, a Summary whose
from or to is not a date written YYYY-MM-DD, an empty branch to check out
or issue to start work on, say); or a configuration save whose If-Match is
not in the form of the ETag a read of the configuration returns.
Unauthorized
Status 401, with WWW-Authenticate: Bearer. The request presented no session
of the running workflow --web, or another run’s. Each run makes a session as
it starts, and the address it prints carries it after #session=; a request
presents it as Authorization: Bearer <session>, and the event stream may take
it as ?session= instead (see
Scripting the API). The session
is checked before anything else about the request, and a page opened without
one says to open the printed address.
Not found
Status 404. The addressed resource does not exist: most often an issue that is
not in the tracker, or a view the configuration does not name — the issue list
and the event stream both refuse a view they do not know rather than answering
with the default one. Staging and unstaging answer it too for a path the working
tree does not list as changed: they move a change the server read, never a path
of the caller’s own. Opening a pull request answers it for a repository the
forge will not show the token. A check’s log answers it for an id no
check of the current pull request’s CI lists now, or when the branch has no
pull request — the log is read only for a check the forge lists. Reading or
saving the configuration answers it where no configuration file applies:
Settings then sets a first one up instead (POST /api/config/setup). A path the
API does not serve answers it too.
Method not allowed
Status 405. The path is one the API serves, but not with the request’s method
— a POST to a read, say. The Allow header lists the methods the path
answers, and so does the detail. The API answers only the methods its contract
declares, so a HEAD is refused here as well.
Conflict
Status 409. The request cannot be applied to the current state — a server not
running in a git repository, for a request that cannot go ahead without reading
it (the command line exits 4 there; the event stream shows the branch, changes
and review empty instead), a working tree with uncommitted changes, a branch
that already exists, nothing staged to commit, no pull request to announce or
to link, no branch checked out (a detached HEAD) to link to an issue or to
unlink from one, an announcement that changed since the page previewed it (the
pull request merged — nothing is posted; preview it again), an
announcement whose linked code owners are not the people its preview showed
tagged (a link changed in Settings or a terminal since — nothing is posted;
preview it again), an
issue the checked-out branch does not name, a move to the review status that
Jira does not offer (the detail names the statuses it does) or wants fields
filled for (the detail names them; the terminal interface’s status picker asks
for them), or a configuration file that changed since Settings read
it — edited on disk, or saved from another tab — which a save refuses rather
than overwrite, short of an edit landing between the save’s check and its write
(Web names that window).
Taskwarrior answers it too, for a task it changed
nothing on — already started, not started, or no longer pending — and for an
undo with nothing to undo. Removing the local data in Settings answers it for a
database file that could not be removed, as one another program holds open can
be on Windows. Every file is set aside before any is removed, so a file that
cannot be set aside leaves them all in place; one that cannot be deleted after
that may leave others already gone, so the area reads the listing again to show
what is left. Close other workflow sessions and remove again (the command line’s
workflow db-clean exits 4 there).
A git run (POST /api/runs) answers it while another run goes, and when
there is nothing to rebase, amend or fix up; editing, merging, finishing and
re-running answer it when the branch’s pull request is not at the point each
needs — open, ready to merge, merged, or with failed CI — read afresh, and a
finish says what was in the way: the branch has not merged, it is not a
branch of its own, there is no base to return to, or it holds commits that
neither merged nor are on its upstream; and an announcement answers it for a
moment already announced, from here, the terminal or workflow announce.
Setting up a first configuration file answers it where one already applies,
or is already at the path chosen: it is never written over, so edit it in
Settings.
Unprocessable
Status 422. The request was understood but cannot be carried out as asked — an
invalid configuration body (a ui.keys map the terminal interface would
refuse to start on among them, or one that changes jira.token_command,
jira.token_env or taskwarrior.program, which change only in the file
itself; one the validation refuses names each setting it refused in
fields, never with a credential’s value), a configuration file on disk that no
longer reads as valid (the configuration in effect stands), a request for an
issue when no tracker is configured, no jira.review_status to move an issue
to, a change Jira refused, a comment with no text or with no tracker to post it
to, a comment the forge turned down (its own reason, such as a body too long, is
in the detail), a file git would not stage or unstage, or a branch git would not
switch to or create (git’s own words stay off the wire, since a fetch it
makes on the way can name the remote; the detail says how to see them), or a
branch’s link to an issue that git could not write to, or remove from, the
repository’s configuration. Linking a branch answers it too for a key that
names no issue — neither a Jira key like PROJ-7 nor a forge number like #42
— and linking or unlinking does for a server that cannot link a branch at
all. A check’s log answers it for a check the forge keeps no log for: a
commit status, or a check run from an app other than GitHub Actions. A push
that ran and failed is answered here with git’s own output, since the reason —
a ref the remote rejected, a hook’s refusal — is in it, with the remote’s URL
or user@host:path address taken out (a bare host git prints — a remote
written host:path, or the host a connection error names — can remain); one
that could not start says to push from a terminal to see why.
A hook run answers it for a hook GET /api/hooks does not list as one a run
by hand can run — one only git runs, one lefthook does not configure, or none
named — and both answer it when lefthook is not installed or its
configuration cannot be read; lefthook’s own words stay off the wire, since
they name the repository, so the detail says to run lefthook dump in a
terminal to see them.
A Jira token that Jira did not accept, a jira.base_url that is not a usable
address, and one with no Jira API behind it are answered here too, pointing at
workflow doctor rather than naming the address. So are a forge token that the
forge did not accept, a forge.kind set without its forge.host, a forge
address with no forge API behind it, and a request the forge refused. A token
the forge turned down is told in the words the terminal uses: which forge, the
scope it asks for, and the forge’s own reason. A pull request the forge turned
down is answered here with the forge’s own reason, while a reviewer or assignee
GitLab does not know never stops one opening; any other open that fails is
answered as a read’s failure is, under the code its cause belongs to. An
announcement the messaging service refused, or one that could not be sent
because messaging has no credential (none set, or a token its command or
variable did not give) or its webhook is not https, is answered here too — never
with the service’s own error, which can name the webhook. So is a change to your
Taskwarrior tasks when there is no Taskwarrior to make it — turned off by
taskwarrior.disabled, one older than 3.5.0, or one whose taskrc has a
malformed line — as is an empty task line or note, or an issue whose tracker key
is not one word. A line Taskwarrior refused is answered here too, in
Taskwarrior’s own words less where its data is and any line naming a server;
they say what in the line it could not take. A sync with no backend named in the
taskrc is answered here, and so is a sync that failed, in fixed words:
Taskwarrior’s name the sync server, so the detail says to run task sync in a
terminal to see them. The Local data area in Settings answers it when there is
no directory to keep the store in (no home directory is set), for a server wired
with no store, and for a removal that finds something other than the store’s own
plain file — a symlink or a directory — where a database file belongs, which it
refuses without removing anything (workflow db-clean exits 1 there).
People and groups answers it when the configuration in effect has no Slack
user token to read the directory with (a webhook, say, or a token Slack holds
no credential for), or no store to keep people in; for a link that names both a
Slack ID and “not on Slack”, or neither; for a Slack ID of the wrong kind for
the owner (a team links to a user group, a person to a user) or one the
channel’s members or the workspace’s user groups do not hold (a person is
checked against the channel the link names, the configured one when it names
none); for a new repository group, never one already saved, that the
workspace’s user groups do not hold; for a token
that lacks a scope the read needs, which the detail names; and for kept data
a build of workflow with another schema wrote, which is left as it is. Nothing
is written then. (A Slack directory read on its own answers a missing scope with
a 200 naming it, so the preview can still post.) An announcement answers it for
mentions that name a user group the announcement did not offer, or that it
was given where it tags no one — only a ready-for-review announcement with a
Slack user token in the configuration in effect at the post tags, so a switch
to a webhook in Settings after the preview lands here — and posts nothing.
Not set up
Status 422. The service the request needs is not set up, so nothing was asked
of it: a Jira token that is not configured, or that its command or variable did
not give; no forge token found ($GITHUB_TOKEN, a gh sign-in, $GITLAB_TOKEN
or forge.token); a base remote (upstream in a fork’s clone, else origin) or a
branch’s push remote that names no repository on a forge, or a forge workflow
cannot tell (set forge.kind and forge.host); no Taskwarrior
installed, a task program that is not Taskwarrior (go-task, most likely), or
one never run; or no git user.email to tell your commits by. The detail says
how to set it up. It is guidance rather than a failure: the event stream
carries it as a panel’s problem, which the page shows as what to set up, and
the Summary leaves such a source out, marking it not_set_up rather than
failed. A service that is set up and refuses is answered under its own code.
Too long
Status 422. A Summary posted to the messaging service is longer, once rendered
for that service, than the service takes in one message, so nothing was sent:
Discord takes 2,000 characters, Slack 40,000, and Teams a payload of 28,000
bytes. The detail names the service and the length against the limit, such as
too long for Discord (2517 of 2000 characters); pick a shorter period. The
Summary’s post_length says the same before the post is asked for. Pick a
shorter period, or edit the text down before posting.
Precondition required
Status 428. A configuration save named no revision to write over: it carried no
If-Match header with the ETag its read returned. Settings always sends one,
so from the browser this is a fault in the page; reload it, then save again.
Unreachable
Status 502. An upstream service — Jira, the Git forge or the messaging service — could not be reached, answered with a redirect (refused, so a credential goes nowhere else), or, for the forge or the messaging service, answered with a status it does not document; or Taskwarrior did not answer in the time it is given. A failed check’s log answers it too when the forge sent the log to an address that is not https or redirected it nowhere, or when the storage it sent the log to did not hand it over — a signed address that expired, or a log since deleted — which is the storage’s failure, not the token’s. The request was well formed; try again once the service is back.
Rate limited
Status 503. An upstream service — Jira, the Git forge or the messaging
service — is limiting requests and asked to be asked again later: a 429, or a
forge’s refusal whose headers ask for a wait. Nothing is wrong with the request
or the setup; wait, then try again. When the service said how long, the answer
carries the wait in seconds, as retry_after in the body and as the
Retry-After header.
Fetch failed
Status 502. Start work fetches the base remote first — upstream in a fork’s
clone, else origin — so the new branch starts from what it holds now, and the
fetch failed: the network, the remote’s address or your credential for it.
Nothing was made. The page offers to branch from what you have, which asks
again without the fetch ("fetch": false); git fetch in a terminal shows
git’s own reason, which the detail leaves out because it names the remote.
Check failed
Status 422. Setting up a first configuration file checks the Jira token with
Jira before anything is written, as workflow config init does, and the check
did not pass: Jira did not accept the token, or could not be reached at the
address given. Nothing was written. The detail says which, naming no address
and no token. (An address that is not an https address, or http to this
machine, or that carries a username and password, is never kept, and is
refused as
Unprocessable instead.) Settings offers to keep the
address and token anyway, which asks again with "keep_unchecked": true, or to
change them.
CI failed
Status 409. An announcement was asked to go now, and a check had failed on its
pull request when the server read its CI again to post it, so nothing was posted
or remembered. Every surface holds to the same rule: a pull request is
announced, ready or merged, only while nothing has failed on it, its CI running
or passed (or reporting no check at all). The way on, for a pull request ready
for review, is to announce it when CI passes ("when": "ci_passes"), which
waits for a run that passes, or to fix the check. A merge has no CI to wait for:
re-run its failed checks on the forge, then announce it once they pass.
A CI the server cannot read posts nothing either; it is answered as the read
that failed, an Unreachable forge among them.
Announced unconfirmed
Status 409. An announcement was asked for — now, or to wait for CI — at a
moment a post of it already began, here, in the terminal or from
workflow announce, and was never confirmed: the session posting it stopped
before the store heard back, or the messaging service never said whether it
took the post, or failed while taking it. It may have gone out, so nothing was posted. The detail says
when the post began. Look in the channel; workflow announce asks before
posting it again.
Not claimed
Status 503. An announcement is claimed in the store before it goes, so it goes
once across every session and process, and the store could not take the
claim — busy with another write past its wait, or its file not writable.
Nothing was posted. Try again in a moment; one held for CI tries again on its
own, for ten minutes. Turning the store off (store.disabled) posts without a
claim, so the same announcement may then be posted twice, from two sessions or
from one.
Internal
Status 500. An unexpected failure the caller cannot act on — among them a
read of the repository that git could not answer, when the request cannot go
ahead without it (a write that has already landed answers all the same, naming
the branch as far as it can, and the event stream shows that panel empty). The
detail stays generic on purpose, and says to try again and to run workflow doctor if it keeps failing; the cause is not in the response but on the
standard error of the workflow --web that answered, one workflow web: line
per failure, a cause of several lines joined by semicolons, with every
credential the configuration holds masked.