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.

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
• failed to spawn vela login
• vela binary not found; install vela or configure VELA_BIN
• vela login already running
• vela login attempt is no longer active

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

Appendix: 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)