Skip to main content

Troubleshooting

Each entry below is a problem that comes up in normal use, with what Bowrain does and what you do next.

Push and pull are out of sync​

kapi keeps a project in step with the server the way git keeps a checkout in step with a remote. It compares content by hash, so a push or pull transfers only what actually changed.

Start with kapi status, which reports the delta between your local project and the server: how many items have changed locally (to push) and how many have changed on the server (to pull). Use kapi diff to inspect the specific changes before you move them.

When both sides have changed, pull before you push:

  1. kapi status: see what diverged.
  2. kapi pull: bring the server's changes into your local project.
  3. Review, then kapi push: send your local changes up.

The server versions every change, so a superseded value stays in history and can be restored. To force a full transfer, for example after a local cache is rebuilt, kapi push --force re-uploads every block and kapi pull --force re-downloads everything, unchanged blocks included. Use these only when you want to skip the content-hash comparison, because they do more work.

See the developer route for the full command set.

AI operations are blocked ("out of credits")​

Hosted workspaces meter AI work in credits: paid plans have a monthly allowance, and every workspace receives a one-time grant of trial credits at creation. When the spendable balance is used up, only AI operations are blocked: AI drafting and AI quality checks return an error indicating the quota is exhausted. Everything that does not call an AI provider keeps working: browsing content, editing by hand, running content memory lookups, pushing, and pulling.

You have three ways forward:

  • Wait for the monthly reset (paid plans). Allowances reset on the 1st of each month at 00:00 UTC. The Free plan has no recurring allowance; its one-time trial credits do not renew.
  • Buy a credit pack. Purchased credits never expire, and they are spent after the plan allowance and trial credits. Bowrain never buys a pack automatically.
  • Upgrade the plan for a monthly allowance (or a larger one).

Two things are never metered against credits: a bring-your-own AI key (those runs go to your own provider account), and a self-hosted deployment (which runs without the billing pipeline and imposes no credit limit). See Security and privacy.

A connector sync failed​

A connector reports its standing through its status: the time of the last sync, the count of items pending pull (changed upstream) and pending push (changed locally), and a list of errors from the most recent attempt. When a sync fails, the error text on the connector status is the first place to look; it usually points at the upstream cause, such as an expired credential or an unreachable source.

Bowrain does not retry connector syncs automatically. Fix the cause, for example by refreshing a credential, correcting the configuration or restoring access to the source, then start the sync again. Re-running a sync is safe: like push and pull, it compares content and moves only what changed.

See Connectors.

The desktop app has pending or failed changes​

The Bowrain desktop app is a working copy of the server. When the server is unreachable, edits you make are queued locally instead of being lost, and the app shows a pending count. When the connection returns, the queue is replayed in order.

Two counts matter, and they mean different things:

  • Pending: changes waiting to be sent. These drain automatically once the server is reachable again.
  • Not sent: changes that will not be retried and need attention. The count opens a list of them: what each change was (a translation, an approval, a note), the file and language it applied to, the wording it carried, and why it was not sent.

A change is not sent in one of three ways:

  • Transient failure (the server was unreachable, a request timed out, or the server was rate-limiting). The app retries the change on later replay passes, up to five attempts, before giving up on it.

  • Permanent rejection. If the server rejects the request itself with a client error (a 4xx status other than request-timeout (408) or rate-limited (429)), the same request would fail again, so the app marks the change failed at once. "Failed-permanent" means the server declined the operation, for example because of a validation error or a permission the account has lost.

  • Queued by an earlier version. An edit or a review an earlier version of the app queued names no version of the translation, so sending it could overwrite a teammate's wording. This version does not send it, and lists it with a notice instead.

The most common permanent rejection is an edit or review made offline to a translation someone else changed before you reconnected. Each queued edit names the version of the translation it was made against. The server refuses one whose translation has changed since, so the teammate's wording stays.

Changes that were not sent do not replay on their own. Open the list from the count, read each translation as it now stands, and make the change again where it still applies, copying its wording from the list. Dismiss an entry once you have dealt with it, or dismiss them all.

Sign-in or session problems​

Access tokens are deliberately short-lived and the clients refresh them silently in the background, so a session that has been idle usually recovers on its own. If sign-in fails outright:

  • Refresh-token reuse. If a refresh token is presented again more than 30 seconds after its rotation, or more than three times in all within that window, the server invalidates the whole session family. Sign in again to start a fresh session.
  • Self-hosted redirect mismatch. A sign-in that returns to an error after the identity provider usually means the OIDC client's redirect URI or public URL does not match the address the browser used. Confirm BOWRAIN_OIDC_PUBLIC_URL and the provider's registered redirect URI against your public HTTPS URL; see Self-hosting.
  • Clock skew. Because sessions use short-lived, time-bounded tokens, a client whose clock is far off can fail validation. Correct the system clock.

Where to see automation run logs​

Automation runs are recorded per project. Each run captures its trigger, its steps, and the outcome of each step; each step keeps its own log lines. Open a project's automation runs to see the history: which runs fired, which steps succeeded or failed, and the per-step logs for a failed step. Check it when an event-driven automation, such as drafting on push, did not do what you expected. See Automation.