What causes "Error setting flow user state at ${key}: ${e.body}" in windmill-labs/windmill?

Call it only within a flow run that has flow user state enabled (check flow settings)

windmill-labs/windmill · error · Error

Error setting flow user state at ${key}: ${e.body}

Error message

Error setting flow user state at ${key}: ${e.body}

What it means

setFlowUserState writes a per-user key/value state for the current flow via the FlowService API. If the underlying API call fails (wrong job context, flow without user state enabled, permission or 404 from the server) and the caller passed errorIfNotPossible=true, the library throws this Error wrapping the API response body; otherwise it only logs to console.error.

Source

Thrown at backend/windmill-runtime-nativets/src/windmill-client.js:10055

async function setState(state) {
  await setResource(state, void 0, "state");
}
async function setFlowUserState(key, value, errorIfNotPossible) {
  !clientSet && setClient();
  if (value === void 0) {
    value = null;
  }
  const workspace = getWorkspace();
  try {
    await JobService.setFlowUserState({
      workspace,
      id: await getRootJobId(),
      key,
      requestBody: value,
    });
  } catch (e) {
    if (errorIfNotPossible) {
      throw Error(`Error setting flow user state at ${key}: ${e.body}`);
    } else {
      console.error(`Error setting flow user state at ${key}: ${e.body}`);
    }
  }
}
async function getFlowUserState(key, errorIfNotPossible) {
  !clientSet && setClient();
  const workspace = getWorkspace();
  try {
    return await JobService.getFlowUserState({
      workspace,
      id: await getRootJobId(),
      key,
    });
  } catch (e) {
    if (errorIfNotPossible) {
      throw Error(`Error setting flow user state at ${key}: ${e.body}`);
    } else {

View on GitHub (pinned to e474e8803c)

Solutions

Call it only within a flow run that has flow user state enabled (check flow settings)
Pass errorIfNotPossible=false (or omit) if the write is best-effort and should only log
Inspect e.body in the message for the underlying API reason and fix accordingly
Verify the run identity has permission to write flow user state in the workspace
Confirm getRootJobId() resolves (WM_JOB_ID set) before using flow-state helpers

Example fix

// before
await setFlowUserState('draft', data, true); // hard failure on any API error
// after
try {
  await setFlowUserState('draft', data, false); // logs instead of throwing
} catch (e) {
  console.warn('flow user state unavailable', e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

const inFlow = process.env.WM_JOB_ID !== undefined;
if (!inFlow) throw new Error('setFlowUserState requires a flow run context');

Type guard

function isApiErrorWithBody(e) { return e && typeof e.body === 'string'; }

Try / catch

try {
  await setFlowUserState(key, value, false);
} catch (e) {
  console.error(`flow user state skipped for ${key}:`, e.body ?? e.message);
}

Prevention

Call flow-state helpers only within flows that enable user state
Prefer errorIfNotPossible=false for best-effort state writes
Log and inspect e.body to learn the server-side rejection reason
Verify job/flow context (WM_JOB_ID, root job resolution) before the call

When it happens

Trigger: Calling setFlowUserState(key, value, true) when the run is not part of a flow (getRootJobId resolution fails), the flow doesn't support user state, or the API rejects the request — any non-2xx/exception from FlowService.setFlowUserState surfaces as this message with e.body.

Common situations: Invoking flow-user-state helpers from a standalone script (no flow context); key collisions or schema rejection by the server; workspace/permission issues for the running identity; transient API errors during flow execution that the developer chose to escalate with errorIfNotPossible=true.

Related errors

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/8f88c6e838efecf7. Report an issue: GitHub.