stablyai/orca · error · RuntimeClientError

authentication_required

authentication_required

Error message

Sign in to Orca and try again.

What it means

Thrown by requireOperation() when an artifact cloud operation returns status 'reconnect-required', meaning the stored credentials are stale or revoked and the user must re-authenticate. This is distinct from 'authentication_unconfigured' (no credentials at all). It surfaces after an RPC like artifacts.list/share returns a non-ok operation status.

Source

Thrown at src/cli/handlers/artifacts.ts:161

    contentType,
    fileName: remoteInput?.fileName ?? basename(sourceKey),
    ...cloudOptions(ctx)
  }
  if (Buffer.byteLength(JSON.stringify(request), 'utf8') > ARTIFACT_CLI_MAX_RPC_BYTES) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Artifact is too large for the Orca CLI transport. Use the browser upload page instead.'
    )
  }
  return request
}

function requireOperation<T>(operation: ArtifactCloudOperation<T>): T {
  if (operation.status === 'ok') {
    return operation.value
  }
  if (operation.status === 'reconnect-required') {
    throw new RuntimeClientError('authentication_required', 'Sign in to Orca and try again.')
  }
  throw new RuntimeClientError('authentication_unconfigured', operation.message)
}

export const ARTIFACT_HANDLERS: Record<string, CommandHandler> = {
  'artifacts list': async (ctx) => {
    rejectRemoteSelectionFlags(ctx)
    const cursor = stringFlag(ctx, 'cursor')
    const response = await ctx.client.call<ArtifactCloudOperation<ArtifactListPage>>(
      'artifacts.list',
      {
        ...cloudOptions(ctx),
        ...(cursor ? { cursor } : {})
      }
    )
    const value = requireOperation(response.result)
    printResult({ ...response, result: value }, ctx.json, formatArtifactListPage)
  },

View on GitHub (pinned to 1136503c6a)

Solutions

1. Run the Orca sign-in flow again (`orca login` or the desktop sign-in) and retry the artifacts command.
2. If sign-in repeatedly fails, check for a revoked/changed password or SSO policy change.
3. Confirm ORCA_CLOUD_AUTH_TOKEN (if used) is still valid; rotate it if expired.
4. After re-auth, verify with `orca artifacts list` before retrying the failing share/update.

Example fix

# before
orca artifacts list   # ERROR authentication_required

# after
orca login
orca artifacts list

// Cannot fully validate client-side; the host decides reconnect-required.
// Mitigation: refresh credentials proactively before a batch.
await ensureSignedIn()

const isReconnectRequired = (op: ArtifactCloudOperation<unknown>): boolean =>
  op.status === 'reconnect-required'

try {
  await dispatch('artifacts list', ctx)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'authentication_required') {
    await signInAgain()
    await dispatch('artifacts list', ctx) // retry once after re-auth
  } else throw e
}

When it happens

Trigger: Any artifacts command whose RPC response has result.status === 'reconnect-required': token expired, refresh failed, server reported revocation, or a password/SSO change invalidated the session. Fires in requireOperation() for list/share/update/unshare/delete.

Common situations: Long-lived CLI session where the OAuth token expired; user changed their Orca password or revoked the app; SSO provider session lapsed; the desktop client was signed out in the background.

Related errors

• authentication_unconfigured
• The active Orca profile is not linked to a cloud account.
• Artifact authentication overrides are available only in deve
• This file has not been shared from the active Orca profile.
• token is required

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/8725cb08e3e6e41e. Report an issue: GitHub.