nexu-io/open-design · warning · VelaWorkspaceBillingSnapshotUnsupportedError

billing_workspace_snapshot_unsupported

billing_workspace_snapshot_unsupported

Error message

workspace billing snapshot unsupported

What it means

A sentinel error (VelaWorkspaceBillingSnapshotUnsupportedError, code billing_workspace_snapshot_unsupported) raised by the default runner when the vela CLI does not support the workspace-snapshot subcommand. It is designed to be caught by resolveVelaWorkspaceBillingProjection so it can fall back to the legacy workspace-balance command. Reaching it as an uncaught error means the fallback layer was bypassed or the caller invoked runVelaCommand directly.

Source

Thrown at apps/daemon/src/integrations/vela-billing.ts:523

    : null;
}

const defaultRunVelaBilling: RunVelaBilling = async (args) => {
  let stderr = '';
  try {
    return await runVelaCommand(['billing', ...args], {
      configuredEnv: { VELA_INVOCATION_SOURCE: 'open-design' },
      maxBuffer: 4 * 1024 * 1024,
      onStderr: (value) => {
        stderr = value;
      },
    });
  } catch (error) {
    if (
      args[0] === 'workspace-snapshot' &&
      isWorkspaceBillingSnapshotUnsupported(error, stderr)
    ) {
      throw new VelaWorkspaceBillingSnapshotUnsupportedError();
    }
    throw error;
  }
};

function isWorkspaceBillingSnapshotUnsupported(error: unknown, stderr: string): boolean {
  const detail = [
    stderr,
    error instanceof Error ? error.message : String(error),
  ].join('\n').toLowerCase();
  return (
    detail.includes('billing_workspace_snapshot_unsupported') ||
    detail.includes('workspace billing snapshot unsupported') ||
    detail.includes('unknown flag: --workspace-id') ||
    (
      detail.includes('unknown command') &&
      detail.includes('workspace-snapshot')
    )

View on GitHub (pinned to 5be4028344)

Solutions

1. Catch VelaWorkspaceBillingSnapshotUnsupportedError at the layer that owns fallback (as resolveVelaWorkspaceBillingProjection already does) and route to workspace-balance.
2. Upgrade the vela binary so workspace-snapshot is supported.
3. If calling runVelaCommand directly with workspace-snapshot, wrap it to translate the sentinel into the legacy path.

Example fix

// before
const stdout = await runVelaCommand(['billing', 'workspace-snapshot', ...], ...);

// after
try {
  const stdout = await runVelaCommand(['billing', 'workspace-snapshot', ...], ...);
  // ... parse snapshot
} catch (err) {
  if (err instanceof VelaWorkspaceBillingSnapshotUnsupportedError) {
    return resolveVelaWorkspaceBillingProjection({ workspaceId, run });
  }
  throw err;
}

import { VelaWorkspaceBillingSnapshotUnsupportedError } from '../integrations/vela-billing.js';

function isSnapshotUnsupported(err: unknown): boolean {
  return err instanceof VelaWorkspaceBillingSnapshotUnsupportedError;
}

try {
  return await runVelaCommand(['billing', 'workspace-snapshot', ...], opts);
} catch (err) {
  if (err instanceof VelaWorkspaceBillingSnapshotUnsupportedError) {
    return await resolveVelaWorkspaceBillingProjection({ workspaceId, run });
  }
  throw err;
}

When it happens

Trigger: An older vela binary (no workspace-snapshot subcommand, unknown --workspace-id flag, or 'unknown command workspace-snapshot' in stderr). The detection logic in isWorkspaceBillingSnapshotUnsupported matches on those stderr substrings.

Common situations: Packaged/bundled vela binary is older than the daemon expects; PATH resolves a stale vela; user-downgraded vela; CI using an old vela mock. The error is expected — the system is built to fall back.

Related errors

• workspace balance response is invalid for ${requestedWorkspa
• vela login already running
• vela login failed to start: ${result.error.message}
• vela login exited before authentication completed (code ${re
• vela login exited before device authorization started (code

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/27e93357f155c484. Report an issue: GitHub.